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PREFACE 


This manual is designed both as a user guide and as a reference 
manual for the MS GW-BASIC Interpreted language (Microsoft Ver. 
3.2) available on the Olivetti Personal Computer. 


SUMMARY 

This manual is divided into two parts. 

Part I, the first 7 chapters, cover: start-up, modes of operation, screen 
editing, general programming, disk I/O, graphics, machine language 
subroutines, event trapping, child processes and asynchronous 
communications. 

Part II, Chapter 8, contains a detailed description of all commands, 
statements, and functions available, with examples for use. 

Appendix A describes the differences between this version of GW- 
BASIC and versions prior to 3.2. 
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1. PROGRAMMING IN GW-BASIC - GENERAL 



ABOUT THIS CHAPTER 


This chapter introduces you to GW-BASIC, highlighting its major 
features, system requirements, the line format, the character set, and 
reserved words. 
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INTRODUCTION 

The GW-BASIC language is the most extensive implementation of 
BASIC available for personal computers. It meets the requirements 
of the ANSI standard for BASIC, and supports many unique features 
rarely found in other BASICS. In addition, GW-BASIC provides 
sophisticated string handling and structured programming features that 
are especially suited for applications development. The GW-BASIC 
language has improved graphics possibilities, and gives users what 
they want from a BASIC - ease of use plus the features that make a 
personal computer perform like a minicomputer. 


GW-BASIC MAJOR FEATURES 

GW-BASIC is a high level language which provides easy ways of solv¬ 
ing commercial and scientific problems. 

Some of the main features of GW-BASIC are as follows: 

• Re-direction of Standard Input (INPUT, LINE INPUT, INPUTS, IN¬ 
KEYS) and Standard Output (PRINT, PRINT USING) 

• Tree-structured directories for organization of archives of programs 
and data and directory management support commands 
(MKDIR/CHDIR/RMDIR) 

• Use of a powerful Screen Editor 

• High-level Graphics: three resolution modes (Medium, High and 
Super) 

• Calls to Assembly language routines, using the CALL or CALLS in¬ 
struction or the USR function 

• Error management and event trapping using user-defined routines 

• RS-232-C standard communication interface management 

• Single or double precision mathematical functions (ATN, COS, LOG, 
EXP, SIN, SQR, TAN) 

• Control of GW-BASIC’s memory allocation for user routines with the 
/M: switch in the GWBASIC command 





• Chaining with common variables: chaining is used to allow programs 
larger than the available memory 

• Declaration statements: variables names can be listed in a declara¬ 
tion statement explicitly specifying the variable to be an integer 
variable, a single or double precision variable, or a string variable. 

SYSTEM REQUIREMENTS 

GW-BASIC, under the MS-DOS operating system, can be run using 

the minimum system configuration. 

A minimum of one disk drive is required. 



SYNTAX CONVENTIONS 


1. Uppercase letters and words, and the symbols listed below, should 
be typed in the actual line exactly as shown. 



( 

) 


/ 

\ 

# 

$ 


< 

> 


In the statement: 

WRITE# filenum, list-of-expressions 

WRITE , # , and the comma (,) after filenum should be typed 
as shown. 
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2. Lowercase letters and words represent ’’variable information” (or 
’’parameters”) that the user must provide. 

In the statement: 

KILL filespec 

filespec should be replaced by a specific value; for example, 
’’myfile”. 

3. The symbols listed below are used to define the syntax of a line, 
but should not be typed in the actual line: 

| vertical stroke ("or” sign), to indicate alternatives 

{ ] braces, to indicate a choice 

[ ] brackets, to indicate optional 

ellipsis, to indicate repetition 

hyphen, to join multiple-name parameters. 

In some statements or commands (e.g. LIST, LUST etc...) the 
hyphen is used as an operator to separate parameters. In this case 
bold face is used to distinguish hyphens that are used for this pur¬ 
pose from hyphens used to join multiple-name parameters. 

4. Braces group related items (divided by a vertical stroke), such as 
alternatives. 

The representation: 

\A\B\C) 

indicates that you must choose one of the items enclosed within 
the braces. 

The representation: 

A 

or 

B 

or 

C 


can also be used. 



5. Brackets also group related items (divided by a vertical stroke); 
however, everything within the brackets is optional and may be 
omitted. 


The representation: 
[A\B\C] 


indicates that you may choose one of the items enclosed within 
the brackets or that you may omit all of the items. 


6. An ellipsis indicates that the preceding item or group of items may 
be repeated more than once in succession. 

The representation: 


A [,B] ... 

indicates that A can be typed alone or can be followed by 




more than once in succession. 


The representation: 

A [ ,list-of-B ] 

is also permitted and has the same meaning as 
A [,B] ... 

7. Characters which appear in a listing in bold face represent 
characters entered through the keyboard. GW-BASIC lines you 
are entering from the keyboard are also represented in bold face. 
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LINE FORMAT 

GW-BASIC lines may contain a maximum of 254 characters and have 
the following format: 

[nnnnn] statement [: statement] ... [comment] CR ■ 

A GW-BASIC program line always begins with a line number (an un¬ 
signed integer in the range 1 to 65,529), and ends with a carriage return 
( CR). A program line is stored in memory as soon as you enter CR. 

A GW-BASIC immediate line, i.e. a line that is executed as soon as 
you enter it, always begins with a letter, as you have to omit the line 
number in this case. 

More than one GW-BASIC statement may be placed on a line, but each 
successive statement must be separated from the last by a colon. 

At the end of a GW-BASIC line (before CR ) you may enter a com¬ 
ment string preceded by a single quotation mark (’). 

A comment string preceded either by the keyword REM or by a single 
quotation mark may also be written just after the line number. 

It is possible to extend a logical line over more than one physical line 
by using the line feed ( CTRL CR ). Line feed lets you continue typ¬ 
ing a logical line on the next physical line without entering a CR . 
From now on, in the interest of brevity, we shall not specify CR at 
the end of a GW-BASIC line. 


Examples 

10 FOR K = 1 TO 20 
is a GW-BASIC program line 
100 GOSUB 1000 ’branch to SUB1 
is a GW-BASIC program line with a comment at the end 


1000 ’SUB1 









is a GW-BASIC program line which contains only a comment 

PRINT A$ 

is a GW-BASIC immediate line. 


LINE NUMBERS 

Every GW-BASIC program line begins with a line number. Line 
numbers indicate the order in which the program lines are stored in 
memory. Line numbers are also used as references in branching and 
editing. Line numbers must be in the range 0 to 65,529. 

For the EDIT, LIST, AUTO, and DELETE commands, a period (.) may 
be used to reference the current line. 

CHARACTER SET 

GW-BASIC recognizes the following sets of characters: 

• Alphabetic characters (upper and lower case letters of the alphabet) 

• Numeric characters (the digits 0 through 9) 

• Special characters (see the following page) 
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Special Characters 

The list of GW-BASIC special characters is summarized below: 


CHARACTER 

ACTION 


Blank 

= 

Equals sign or assignment symbol 

+ 

Plus sign 

- 

Minus sign 

* 

Asterisk or multiplication symbol 

/ 

Slash or division symbol 

A 

Up arrow or exponentiation symbol 

( 

Left parenthesis 

) 

Right parenthesis 

% 

Percent sign or integer type declaration 
character 

# 

Number (or pound) sign or double precision 
type declaration character 

$ 

! 

[ 

1 

Dollar sign or string type declaration character 
Exclamation point or single precision type 
declaration character 

Left bracket 

Right bracket 

Comma 

J 

Period or decimal point 

Single quotation mark (apostrophe) 

Double quotation mark (string delimiter) 
Semicolon 

Colon 

& 

Ampersand 

? 

Question mark (PRINT abbreviation) 

< 

Less than 

> 

Greater than 

\ 

Backslash or integer division symbol 


At sign 

— 

Underscore 








RESERVED WORDS 


GW-BASIC comprises a set of statements, commands, function names, 
and operator names which are treated as reserved words, and which 
cannot be used as variable names. The total list of GW-BASIC reserv¬ 
ed words is as follows: 


ABS 

DELETE 

IOCTLS 

AND 

DIM 

KEY 

ASC 

DRAW 

KILL 

ATN 

EDIT 

LEFTS 

AUTO 

ELSE 

LEN 

BEEP 

END 

LET 

BLOAD 

ENVIRON 

LINE 

BSAVE 

ENVIRONS 

LIST 

CALL 

EOF 

LLIST 

CALLS 

EQV 

LOAD 

CDBL 

ERASE 

LOC 

CHAIN 

ERDEV 

LOCATE 

CHDIR 

ERDEVS 

LOCK 

CHR$ 

ERL 

LOF 

CINT 

ERR 

LOG 

CIRCLE 

ERROR 

LPOS 

CLEAR 

EXP 

LPRINT 

CLOSE 

FIELD 

LSET 

CLS 

FILES 

MERGE 

COLOR 

FIX 

MID$ 

COM 

FNxxxxxxxx 

MKDIR 

COMMON 

FOR 

MKD$ 

CONT 

FRE 

MKI$ 

COS 

GET 

MKSS 

CSNG 

GOSUB 

MOD 

CSRLIN 

GOTO 

MOTOR 

CVD 

HEX$ 

NAME 

CVI 

IF 

NEW 

CVS 

INKEYS 

NEXT 

DATA 

INP 

NOT 

DATES 

INPUT 

OCT$ 

DEF 

INPUTS 

OFF 

DEFDBL 

INPUT# 

ON 

DEFINT 

INSTR 

OPEN 

DEFSGN 

INT 

OPTION 

DEFSTR 

IOCTL 

OR 
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OUT 

PAINT 

PALETTE 

PEEK 

PEN 

PLAY 

PMAP 

POINT 

POKE 

POS 

PRESET 

PRINT 

PRINT# 

PSET 

PUT 

RANDOMIZE 

READ 

REM 

RENUM 

RESET 

RESTORE 

RESUME 

RETURN 

RIGHTS 

RMDIR 

RND 

RSET 

RUN 

SAVE 

SCREEN 

SGN 

SHELL 

SIN 

SOUND 

SPACES 

SPC 

SQR 

STEP 

STOP 

STR$ 

STRINGS 

SWAP 

SYSTEM 

TAB 

TAN 

THEN 

TIMER 

TIMES 

TO 

TROFF 

TRON 

UNLOCK 

USING 

USR 

VAL 

VARPTR 

VARPTRS 

VIEW 

WAIT 

WEND 

WHILE 

WIDTH 

WINDOW 

WRITE 

WRITE# 

XOR 








2. GETTING STARTED 



ABOUT THIS CHAPTER 


This chapter explains how to enter and leave GW-BASIC, the modes 
of operation, the use of the keyboard and the GW-BASIC Screen Editor. 
It also explains how to enter, list, save, load, modify, and execute a 
GW-BASIC program. 
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MODIFYING PROGRAM 2-17 
LINES 



GETTING STARTED 


INITIALIZATION PROCEDURE 

To start GW-BASIC, the MS-DOS operating system must first be in¬ 
stalled. When MS-DOS has been installed and the system prompt: 

A> 

is displayed, enter the GWBASIC command: 

GWBASIC 

to load GW-BASIC from the diskette inserted in drive A into memory. 
Upon loading, GW-BASIC you can: 

• insert a diskette containing your GW-BASIC programs and execute 
a program. For example you can enter: 

run ”b:myfile” 

if ’’myfile” is the GW-BASIC program you want to run from the 
diskette inserted in drive B 

• enter GW-BASIC program or immediate lines (see ’’Modes of Opera¬ 
tion” below). For example: 

. 10 K = 10 

20 FOR J = 1 TO 2 

etc... 

These are program lines. When you enter them, they are stored in 
memory to form a program. To execute it, you must enter the RUN 
command. 


Remarks 

The GWBASIC command may be entered with several options to op¬ 
timize memory occupation, redirecting standard input or output, etc. 
(See the GWBASIC command in Chapter 8 for details.) 





LEAVING GW-BASIC 

To exit from GW-BASIC and return to MS-DOS, enter: 

SYSTEM 

This closes all data files before returning to MS-DOS; your GW-BASIC 
program is lost, while MS-DOS remains resident. 

When the MS-DOS system prompt ( A> ) appears once more, you 
can enter another MS-DOS command. 


MODES OF OPERATION 

The GW-BASIC Interpreter may be used in either of two modes: ’’im¬ 
mediate mode” or ’’program mode”. 

In ’’immediate” (or ’’direct”) mode, statements and commands are 
executed as they are entered. They are not preceded by line numbers. 
After each direct statement followed by a carriage return, the screen 
will display the ”Ok” prompt. Results of arithmetic and logical opera¬ 
tions may be displayed immediately and stored for later use, but the 
instructions themselves are lost after execution. Immediate mode is 
useful for debugging and for using the GW-BASIC Interpreter as a 
calculator for quick computations that do not require a complete 
program. 


Example 

Ok 

PRINT 45 + 3 

48 

Ok 


Program (or ’’indirect”) mode is used for entering programs. Program 
lines are preceded by line numbers and are stored in memory as soon 
as they are entered. The program stored in memory is executed by 
entering the RUN command. 
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Example 

Ok 

10 PRINT 45 + 3 
RUN 

48 

Ok 


KEYBOARD 

Two different types of keyboard are available for the Olivetti PC: 
KEYBOARD 1 and KEYBOARD 2. All the keyboards have several na¬ 
tional versions. See the ’’Installation and Operation”manual for a full 
description of the keyboard(s) provided with your Olivetti PC. 


FUNCTION KEYS 

There are 10 function keys on Keyboard 1 and 18 on Keyboard 2. 

These function keys can be tailored to the User’s needs using the KEY 
and ON KEY(n) GOSUB statements. 

The KEY statement can be used to assign a specific command or se¬ 
quence of characters to a function key, other than the pre-assigned 
standard commands. The ON KEY(n) GOSUB statement can be used 
to generate program interrupts via a specified function key. 

Refer to Chapter 8 for further details. 




TYPEWRITER KEYBOARD 


The standard typewriter keyboard, located in the center, is used to enter 
letters, numbers, special characters, and control characters. 


Shift Keys 

If you want to enter upper case letters or the upper symbol on those 
keys containing two symbols, hold down one of the two t keys (on 
(Keyboard t), or one of the two SHIFT keys (on Keyboard 2), and press 
the corresponding key. 

From now on we shall always refer to the t keys as SHIFT keys by con¬ 
vention. 


Carriage Return Key 


The carriage return key is identified by the symbol 
tion we shall refer to this key as the CR key. 


By conven- 


. You must press CR to close a GW-BASIC line and send it to the system 
for processing. 


Shift Lock for Letters 

You can enable or disable Shift Lock for letters (A-Z) by pressing 

CAPS LOCK. 

The CAPS LOCK key is similar to a typewriter Shift Lock Key, but it only 
gives you uppercase letters, and will not give you the upper symbols 
on the numeric or other keys. 
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Backspace 

The backspace key — (on Keyboard 1) or BS (on Keyboard 2) 
moves the cursor one position to the left erasing the last character 
you have typed. 

To move the cursor to the left without erasing any characters, you 
should use the Cursor Left Key. 

Control Characters 

You can generate control characters by holding down the CTRL or 
ALT key while pressing another key. GW-BASIC recognizes the 
following control characters: 


CONTROL 

ACTION 

CHARACTER 


CTRL BREAK 

CTRL BREAK can be used for different purposes: 

1. To interrupt the program at the following GW- 
BASIC instruction and return to GW-BASIC 
Command Level. 

2. To cancel automatic line numbering mode while 
entering a program. 

3. To return to Command Level, without saving any 
changes that you made to the current line. 

CTRL G 

Sounds the bell. 

CTRL NUM LOCK (on 

Keyboard 1) CTRL 
FUNCT LOCK (on 
Keyboard 2) 

Causes the system to ’pause’ so as to temporarily 
halt printing or program listing. The pause con¬ 
tinues until you press any key (except SHIFT , 
CTRL or ALT ). 

► 











CONTROL 

CHARACTER 

ACTION 


ALT CTRL DEL 

Performs a System Reset by holding down the 
CTRL and ALT keys, and then pressing the DEL key. 

CTRL PRTSC (on 

Keyboard 1) CTRL 

SCR PRT (on 

Keyboard 2) 

All text sent to the screen is also sent to the system 
printer. You can stop printing by repeating the key 
sequence. 

If you press PRTSC while holding down SHIFT on 
Keyboard 1, or if you press SCR PRT ob Keyboard 
2, MS-DOS will make a single printed copy of the 
entire display screen. 

To print both text and graphics, you have to use 
the MS-DOS GRAPHICS command before enter¬ 
ing GW-BASIC. 

CTRL L 

Outputs a formfeed character. It has the same func¬ 
tion as the CLS statement, i.e. it clears the screen 
or the current graphics viewport (if a viewport has 
been defined). 

CTRL Z 

Sets an end of file condition. See the OPEN COM 
statement. 


Other control characters are described in the subsection entitled 
’’Special Screen Editor Keys” later in this chapter. 
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Direct Entry of GW-BASIC Keywords 

A GW-BASIC Keyword is entered by holding down the ALT key 
while pressing one of the alphabetic keys (A - Z). Keywords associated 
with each letter are listed below. 


A - AUTO 
B - BSAVE 
C - COLOR 
D - DELETE 
E - ELSE 
F - FOR 
G - GOTO 
H - HEX$ 

I - INPUT 

J _ ★ * * * 

K - KEY 
L - LOCATE 
M - MOTOR 


N - NEXT 
O - OPEN 
P - PRINT 

Q ★ ★ * * 

R - RUN 
S - SCREEN 
T - THEN 
U - USING 
V - VAL 
W - WIDTH 
X - XOR 


**** = unused keys 


NUMERIC KEYPAD 

A group of 15 keys on Keyboard 1 and 27 keys on Keyboard 2, at the 
right-hand side of the keyboard. It is arranged much like a standard 
calculator’s keypad and is called the ’’numeric keypad”. It includes 
not only the numbers 0 through 9, the decimal point, the plus (+) and 
minus (-) keys, but also cursor movement keys, PGUP , PGDN , 
HOME , NUMLOCK (on Keyboard 1), FUNCTLOCK (on Keyboard 
2), SCROLL LOCK (on Keyboard 1), SCROLL ON (on Keyboard 2), 
BREAK , END , INS , DEL , etc. 

Note that some keys like SCROLL LOCK , PGUP , and PGDN etc., 
are not used by GW-BASIC, but you may assign meanings to them 
within a GW-BASIC program. 

Number Lock State (Keyboard 1) 

You can press the NUM LOCK key (on Keyboard 1) to shift the 
numeric keypad into upper-case. This mode provides the numbers 0 
through 9 and the decimal point. (Holding down one of the two 
SHIFT keys produces the corresponding lower-case keys in this 
mode.) To return to lower-case, press NUM LOCK once again. 




Function Lock State (Keyboard 2) 

You can press the FUNCT LOCK key (on Keyboard 2) to shift the 
numeric keypad into the lower-case. This mode provides the functions 
(like HOME, INS, DEL, END, PGUP, PGDN). Holding down one of the two 
SHIFT keys produces the corresponding upper-case keys in this mode. 
To return to upper-case, press FUNCT LOCK once again. 


THE GW-BASIC SCREEN EDITOR 

All text entered while GW-BASIC is at command level is processed 
by the GW-BASIC Editor. This is a ’’screen line editor” which allows 
you to change a line anywhere on the screen (only one line at a time). 
It is important to note that changes are only registered when you press 
CR on that line. 


SPECIAL SCREEN EDITOR KEYS 

The GW-BASIC Editor recognizes 9 Numeric Keypad keys, the 
Backspace key, and the CTRL key, to move the cursor, insert or delete 
characters. 

The keys and their functions are listed below. 


KEY 

FUNCTION 

HOME 

HOME: Positions the cursor in the top left hand cor¬ 
ner of the screen. 

CTRL HOME 

CLEAR SCREEN: Clears the screen and moves the 
cursor to the ’’Home” position. 

l 

CURSOR UP: Moves the cursor up one line. 
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KEY 

FUNCTION 

i 

CURSOR DOWN: Moves the cursor one position 
down. 

*— 

CURSOR LEFT: Moves the cursor one position left. 
When the cursor is moved beyond the left limit of 
the screen, it appears at the right side of the screen 
on the preceding line. 

—* 

CURSOR RIGHT: Moves the cursor one position 
right. If the cursor is moved beyond the right limit 
of the screen, it appears at the left side of the screen 
on the following line. 

CTRL — 

NEXT WORD: Moves the cursor to the beginning 
of the following word, i.e., to the next character to 
the right of the cursor in the set [A..Z] or [a..z] or 
[0..9], which follows a blank or special character. 

For example, in the following line: 

30 IF L < =0 THEN 20 

The cursor is under the letter L. If you press 
CTRL —*, the cursor will move to the beginning 
of the next word, which is 0: 

30 IF L < =0 THEN 20 

If you press CTRL —► again, the cursor will move 
to the next word, which is THEN: 

30 IF L< =0 THEN 20 















KEY 

FUNCTION 

CTRL — 

PREVIOUS WORD: Moves the cursor to beginn¬ 
ing of the preceding word, i.e., to the first character 
to the left of the cursor (in the set [A..Z] or [a..z] 
or [0..9]) which is preceded by a blank or a special 
character. 

For example: 

30 IF L < =0 THEN 20 

The cursor is under the letter T. If you press CTRL 
, the cursor will move to 0. Pressing CTRL 
again, it will move to L. 

END 

END, APPEND: Moves the cursor from its current 
position to the end of the logical line. Subsequent¬ 
ly entered characters are appended to the line. 

CTRL END 

ERASE TO END OF LINE: Erases from the current 
cursor position to the end of the logical line, i.e., 
until the carriage return is found. 

INS 

SWITCH INSERT/OVERWRITE MODE: Switches 
into or out of Insert Mode. If Insert Mode is off (Over¬ 
write Mode on), then it turns it on. If Insert Mode 
is on, then it turns it off (sets Overwrite Mode). 

Insert mode is also turned off by pressing one of 
the cursor movement keys or CR. 

The Insert Mode cursor is a half-height blinking 
block in Text Mode and is a blinking triangle to the 
left of each character in Graphics Mode. 
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KEY 


FUNCTION 


Overwrite mode is indicated by a different cursor, 
which is a slow-blinking under-line. In Insert Mode 
the character immediately above, together with 
those following the cursor, move to the right as 
characters are entered at the current cursor posi¬ 
tion. As characters disappear off the right side of 
the screen, they reappear on the left on the follow¬ 
ing line. 


When out of Insert Mode, characters typed will 
replace existing characters on the line. 


TAB: When out of Insert Mode, pressing —► | 
moves the cursor over characters until the next tab 
stop is reached. Tab stops occur every 8 character 
positions starting from position 1. 

For example, given the line below: 

20 INPUT ’’Length”; L 

If you press the —* | key, the cursor will move 

to the 17th position as shown: 

20 INPUT ’’Length”; L 

When in Insert Mode, pressing —► | causes 
blanks to be entered from the current cursor posi¬ 
tion to the next tab stop. As characters disappear 
off the right side of the screen, they reappear on 
the left on the following line. 











KEY 

FUNCTION 


For example, given the line below: 

20 INPUT ’’Length”; L 

Blanks are entered up to the 17th position by press¬ 
ing the INS key and then the — | key. 

20 INPUT ” Length”; L 

DEL 

DELETE CHARACTER: Erases the character 
located at the current cursor position. All characters 
which follow the deleted character shift one posi¬ 
tion left. If a logical line extends beyond one 
physical line, characters on subsequent lines shift 
left one position, and the character in the first col¬ 
umn of each subsequent line is moved up to the 
end of the preceding line. 

on Keyboard 

1 (or BS on 
Keyboard 2) 

BACKSPACE: Causes the last character typed to 
be deleted, or deletes the character to the left of 
the cursor. All characters to the right of and above 
the cursor shift left one position. Subsequent 
characters and lines within the current logical line 
move up as with the DEL key. 

CTRL CR 

LINE FEED: Causes subsequent text to start 
automatically on the next screen line. 
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KEY 

FUNCTION 

ESC 

DELETE LINE: The entire logical line containing the 
cursor is cleared. The line is not entered for pro¬ 
cessing. If it is an existing program line, it is not 
deleted from the program currently in memory. 

CTRL BREAK 

BREAK: Returns to Command Level, without sav¬ 
ing any modifications that were made to the cur¬ 
rent line being edited. Unlike ESC , it does not 
delete the line from the screen. 


CORRECTING THE CURRENT LINE 

All text entered at GW-BASIC Command Level is processed by the 
Screen Editor. You can therefore use any of the Special Screen Editor 
Keys described above. 

GW-BASIC remains at Command Level after the prompt Ok and until 
a RUN command is received. 










Character Modification 

If you make a mistake while entering a line then proceed as follows: 


STEP 

ACTION 


1 

You discover the error. For example, suppose you 
have typed: 

RUN ”K,PROGR_ 

when you should have entered: 

RUN ”A:PROGR_ 

2 

Use Cursor-Left, or other cursor movement keys, 
to move the cursor to the appropriate position: 

RUN ”K,PROGR 

3 

Type the correct character over the wrong ones: 

RUN ”A:PROGR 

4 

Move the cursor to the end of the line using Cur¬ 
sor Right or END keys: 

RUN ”A:PROGR_ 

5 

Continue typing if the line is not finished: 

RUN ”A:PROGRAM1”_ 


6 

Enter CR to pass the line to GW-BASIC. In this 
case the specified program is loaded from the 
diskette inserted in drive A and run. 
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Character Insertion 

If you accidentally omit characters in the line you are enterinq then 
proceed as follows: 


STEP 

ACTION 

1 

You notice the error. 

Suppose you entered: 

10 FO K = 1 TO 

instead of: 

10 FOR K= 1 TO_ 

2 

Use Cursor-Left, or other cursor movement keys, 
to move the cursor to the appropriate position: 

10 FO_K = 1 TO 

3 

Press INS and type the letter R: 

10 FOR_K = 1 TO 

Note that, entering Insert Mode, the cursor 
becomes a halfheight block. 

4 

Press INS again to return to Overwrite Mode 
and Cursor-Right or END to move the cursor to 
the end of the line: 

10 FOR K = 1 TO_ 

















Character Deletion 

If you accidentally type an extra character in the line you are entering, 
then proceed as follows: 



STEP 

ACTION 

1 


You discover the error. 

For example, suppose you typed: 

GOTTO_ 

instead of: 

GOTO_ 

2 


To erase the extra T, press Cursor-Left, or other 
cursor movement keys, to move the cursor to the 
appropriate position: 

GOTTO 

3 


Press DEL : 

GOTO 

4 


Move the cursor using Cursor-Right: 

GOTO_ 

5 


Continue typing: 

GOTO 1000_ 
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Deleting Part of a Line 

To erase a line from the current cursor position, press CTRL END 


Deleting an Entire Line 

To cancel the line you are entering, press ESC anywhere in the line. 
It is not necessary to press CR . 


MODIFYING PROGRAM LINES 

Any line of text beginning with a number (0 to 65529) is considered 
to be a ’program line’. Suppose you have entered a program, i.e. a 
sequence of program lines, that you want to modify: 


IF you want to... 

THEN... 

add a new line to your 
program 

enter a valid line number followed by at least one 
non-blank character, followed by CR. 

replace an existing line 

enter a line number that matches an existing one, 
followed by the contents of the new line. The new 
line will replace the existing one. 

delete a line 

enter the line number of the line to be deleted, 
followed by CR. 


An ’’Undefined line number” error is returned if an 
attempt is made to delete a line which does not 
exist. 


Note: ESC should not be used to delete pro¬ 
gram lines, since this erases from the screen only, 
and not from the program in memory. 
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IF you want to... 

THEN... 

delete a group of lines 

enter a DELETE command indicating the range of 
lines to be deleted. 

delete the program 
resident in memory 

enter a NEW command. 

modify a program line 
which is already 
displayed on the 
screen 

move the cursor to the appropriate position (by the 
cursor movement keys); modify the line using any 
of the techniques described above to change, 
delete or insert characters to the line; press CR. 
to pass the modified line to GW-BASIC. 

modify a program line 
which is not displayed 
on the screen 

use the EDIT command to display the line, or the 
LIST command to display a group of lines including 
the line you want to modify, move the cursor to the 
appropriate position, modify the line, and press 

CR 

Note: You can edit any line as long as it is visible 
on the screen. Once an immediate line has been 
sent to the system by pressing CR , there is no 
way to edit it; this is not the case with program lines, 
as they may always be recalled for editing to the 
screen. 


Remarks 

Changes to a line are recorded when a carriage return is entered while 
the cursor is somewhere on that line. The carriage return enters all 
changes for that logical line, and, up to the 255 character line, limita¬ 
tion, no matter how many physical lines are included and no matter 
where the cursor is located on the line. 


2-18 


GW-BASIC INTERPRETER USER GUIDE 



















GETTING STARTED 




Note that any modifications you made by using the GW-BASIC Screen 
Editor only change the program in memory. To store the updated ver¬ 
sion of your program in a disk file you must use the SAVE command. 


USING YOUR SYSTEM AS A CALCULATOR 

You can use your Personal Computer as a calculator for quick com¬ 
putation, and debugging purposes. 

When you are in GW-BASIC, and the Ok prompt is on the screen, you 
can enter PRINT (or simply a question mark ”?”), followed by any ex¬ 
pression, and CR . The expression is evaluated and its value 
displayed. 


You can also enter LET, followed by any variable name, the assign¬ 
ment operator ( = ), any expression, and CR . The expression is 
evaluated and its value is assigned to the specified variable. You can 
use the variable to represent that value in successive computations. 
The keyword LET is optional, you can begin the line simply usinq the 
variable name. 

The following table gives some examples. 


DISPLAY 

COMMENTS 

PRINT 3 

3 

The constant 3 is displayed. 

Ok 


PRINT 2 + 3 

The expression 2 + 3 is evaluated, and its value ( 5 ) 

5 

Ok 

is displayed. 

LET A = 15.21 

The constant 15.21 is assigned to the variable A. 

Ok 

You can use A in successive computations to repre¬ 
sent this value. 
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DISPLAY 

COMMENTS 


?A-1 

The expression A-1 is evaluated, and its 

> value 

14.21 

(14.21) is displayed. 


Ok 

Note: ? is equivalent to PRINT. 


B = 2.3 

The constant 2.3 is assigned to the variable B. The 

Ok 

keyword LET is optional, you may begin with a 


variable name. 


?A*B 

The expression A*B is evaluated. Its value (34.983) 

34.983 

Ok 

is displayed. 


?A*B-40 

The expression A*B-40 is evaluated, and its value 

-5.017002 

(-5.017002) is displayed. 


Ok 

Note: If a value is negative, the minus 

sign is 


displayed, if a value is positive, no sign is displayed. 


ENTERING A PROGRAM 

A GW-BASIC program consists of a series of statements. A statement 
is a complete instruction in GW-BASIC, telling your computer to per¬ 
form specific operations. 

You can enter either one or several statements per line. In the latter 
case, each statement must be separated from the last by a colon (:). 

Each line in a GW-BASIC program begins with a line number: an in¬ 
teger greater than or equal to 0 and less than or equal to 65529 and 
ends when you press CR . 
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A GW-BASIC line may contain a maximum of 255 characters including 
the carriage return. The extra characters will be truncated when vou 
enter CR . 

When you are in GW-BASIC, and the Ok prompt is on the screen, you 
can enter a program. 

First of all enter: 

NEW 

This will clear the memory. 

Then enter: 

10 REM RECTI 
20 INPUT ”Length”;L 
30 IF L< =0 THEN 20 
40 INPUT ”Width”;W 
50 IF W< = 0 THEN 40 
60 LET AREA = L*W 

70 PRINT ”Area = ”;AREA;” L = ”;L;” W=”;W 
80 GOTO 20 
90 END 

It is conventional to use an interval of 10 between each line number. 
This allows you to modify the program simply by inserting statements 
between existing lines. 

These statements form a complete program that solves a very simple 
problem. The problem is to find the area of a rectangle by entering 
the values of length and width via the keyboard. It has been selected 
both for its simplicity and to illustrate a variety of the GW-BASIC 
language features. Other more concise solutions exist. You can exit 
from the program by pressing CTRL BREAK. 


AUTOMATIC LINE NUMBERING 

You can use the AUTO command, to generate a line number 
automatically each time you press CR. You can exit AUTO mode bv 
pressing CTRL BREAK. 







LISTING A PROGRAM 


Once a program is in main memory it can be listed. To list your pro¬ 
gram, enter either the LIST command (the listing will appear on the 
screen) or, if a printer is connected, the LUST command (the listing 
will be printed out). 

The LIST and LLIST commands edit your program by converting to 
upper case letters any keywords, variable names, and function names 
and to PRINT any question mark (?) used instead of PRINT. Moreover, 
statements are ordered in ascending line number sequence, even 
though you may have entered them in a different order. 

To list our sample program on the screen enter: 

LIST 

The screen display is as follows: 

LIST 

10 REM RECTI 
20 INPUT ”Length”;L 
30 IF L < =0 THEN 20 
40 INPUT ”Width”;W 
50 IF W < =0 THEN 40 
60 LET AREA = L*W 

70 PRINT ”Area = ”;AREA;” L = ”;L;” W = ”;W 
80 GOTO 20 
90 END 
Ok 

Note that at the end of a listing your system enters command level 
and displays the Ok prompt; the program can now be edited as 
required. 

SAVING A PROGRAM 

A program is kept in memory as long as your computer is switched 
on and you are in GW-BASIC. As soon as you turn off your computer, 
do a system reset or exit from GW-BASIC, your program is lost. If you 
want to retain your newly written program for future use, then you must 
enter a SAVE command to store the program on a disk. 
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You should save the current program (i.e. the program presently resi- 
dent in the main memory) on the following occasions: 


IF you want to ... 

THEN ... 

turn off the machine 
or do a system reset) 

save the current program (unless you already have 
a copy). For example: 

SAVE ”A:RECT1” 

enter another program 
from keyboard 

save the current program (unless you already have 
a copy). 

load another program 
from disk (by entering 
a LOAD or RUN 
command) 

save the current program (unless you already have 
a copy). 

return to MS-DOS (by 
entering a SYSTEM 
command) 

save the current program (unless you already have 
a copy). 

replace the old ver¬ 
sion of your program 

save the current program on the same disk, and 
with the same file name as the old version. 

save the current pro¬ 
gram in ASCII 
(source) format 

specify the A option in the SAVE command. For 
example: 

SAVE ”A:RECT1 ”, A 

protect the current 
program against any 
attempt to list, edit or 
save it again 

specify the P option in the SAVE command. For 
example: 

SAVE ”A:RECT1 ”,P 




















LOADING A PROGRAM 

If the program you want to enter into the main memory resides on a 
disk, you must issue a LOAD command. LOAD deletes all variables 
and program lines currently residing in memory, thus before entering 
a LOAD command you should save the current program if you want 
to use it again, unless you already have a copy. 

To load a program file from a disk, you must specify the drive before 
the file name, unless the file resides on the default drive. For example: 

LOAD ”B:ROOT1” 

if the program ROOT1 resides on the diskette inserted in drive B. 

If you specify the R option, all open data files are kept open and the 
program is run after it is LOADed. For example: 

LOAD ”B:ROOT1”,R 

If you do not specify the R option, LOAD closes all data files. 


EXECUTING A PROGRAM 

Once a program is in main memory, it can be executed (or ’’run”, as 
this is frequently called). To tell your system to execute a program, 
you must enter a RUN command (or a LOAD with the option R). 

The RUN command runs the current program, i.e. the program cur¬ 
rently in memory, or loads a program from a disk and runs it (if you 
enter a file specifier after the keyword RUN). For example: 

RUN ”B:RECT 1 ” 

Note that a file specifier is a string expression or, in particular, a string 
constant. If it is a string constant as in the example above it must be 
enclosed within quotation marks (”). 

If you specify the R option all open data files are kept open, thus you 
can re-use these files in the new program without having to open them 
again. 
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Before entering a RUN filespec (or RUN filespec, R), save your cur¬ 
rent program (unless you already have a copy). 


GW-BASIC statements are executed in line number sequence, unless 
a control statement (GOTO, ON...GOTO, IF...GOTO...ELSE, 
IF...THEN...ELSE, FOR/NEXT, WHILE/WEND) or a subroutine call 
statement (GOSUB, ON...GOSUB) dictates otherwise. 


RUNNING A SAMPLE PROGRAM 

Let us run our sample program. Let us suppose it is already in memory, 
entered through the keyboard or loaded from disk by the LOAD 
command. 

Enter: 

LIST 


to check that this program is in main memory. The listing will appear 
on the screen. At the end of the listing, when Ok appears on the screen, 
enter: 


RUN 

The following listing is displayed: 


LIST 

10 REM RECTI 
20 INPUT ”Length”;L 
30 IF L< =0 THEN 20 
40 INPUT ”Width”;W 
50 IF W< =0 THEN 40 
60 LET AREA = L*W 


70 PRINT ”Area = ”;AREA;” 
80 GOTO 20 
90 END 
Ok 

RUN 

Length? 3.5 
Width? 4.2 


L = ”L” 


Area= 14.7 L= 3.5 W= 4.2 
Length? -7.3 
Length? 7.3 
Width? 1.3Q 


W = ”;W 








?Redo from start 
Width? 1.32 

Area = 9.636 L= 7.3 W= 1.32 
Length? CTRL BREAK 
Break in 20 
Ok 

Your system begins executing statements sequentially. Because state¬ 
ment 10 is a REM(ark) it is not executed; execution in this case starts 
with statement 20. 

When an INPUT statement is encountered (see statements 20 and 40) 
program execution is suspended and your system prompts a message 
indicating that you should enter a value. You could enter for example 
3.5 for the length and 4.2 for the width. 

Statement 60 calculates the value of AREA. Statement 70 displays the 
values of AREA, L and W. Statement 80 returns control to statement 20. 

If you enter a negative value (e.g. -7.3), for L, statement 20 is executed 
again, as statement 30 returns control to statement 20 if L is negative 
or zero. 

If you enter a negative value for W, statement 40 is executed again, 
as statement 50 returns control to statement 40, if W is negative or 
zero. 

If you enter a string value for L or W (e.g. 1.3Q for W) the system 
displays an error message: 

?Redo from start 

and you must re-enter the Value. 

This program continues to run until you press CTRL BREAK to stop 
execution. Your system displays a ’’Break in nnnnn ” message and 
returns to Command Level. To resume execution enter: 

CONT 
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PROGRAM INTERRUPTS 

Three types of program interrupts are possible: 

• Manual interrupts 

• Automatic interrupts 

• Programmable interrupts 


IF... 

THEN... 

you press CTRL 
BREAK , (manual in¬ 
terrupt), or a STOP, 
or an END statement 
is executed 
(programmed inter¬ 
rupt) 

the program is interrupted, GW-BASIC enters Com¬ 
mand Level and displays Ok. CTRL BREAK and 
STOP do not close any data files but display a 
’’Break in nnnnn" message. END closes all data 
files but does not display a ’’Break in nnnnn" 
message. 

In any case you can resume execution by entering 
a CONT command. You can display program 
variables (by immediate PRINT or PRINT USING 
statements) or change their values (by immediate 
LET or SWAP statements). You can also display 
program lines by an EDIT or LIST command, and 
modify them. 

If you modify lines, you cannot continue execution 
via a CONT command. You can only rerun the pro¬ 
gram by entering RUN. 

a syntax error is 
found (automatic in¬ 
terrupt) 

the program is interrupted, GW-BASIC displays the 
error message at the line that caused the error, 
positioning the cursor under the first digit of the line 
number. 













IF... 

THEN... 


You can modify the line, and then rerun the pro¬ 
gram by entering RUN. You cannot continue ex¬ 
ecution by entering CONT. 

If you want to examine the contents of some 
variables before making any modifications you 
should press CTRL BREAK to return to Com¬ 
mand Level. After examining the contents of the 
variables you can edit the line and rerun the 
program. 

For example: 

10 A = 2$6 

RUN 

?Syntax Error in 10 

Ok 

10 A = 2$6 

an error (other than a 
syntax error) is found 
(automatic interrupt) 

the program is interrupted, GW-BASIC displays the 
error message, enters Command Level and 
displays Ok. 

You can either display program variables or display 
program lines by an EDIT or LIST command, and 
then modify them. 

You cannot continue execution by entering a CONT 
command, but you can rerun the program by enter¬ 
ing RUN. 

For example, running a program which contains: 

100 FOR K = 

will cause: 

Missing operand in 100 

Ok ^ 
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IF... 

THEN... 

an error occurs and 
the error trapping is 
enabled (programmed 
interrupt) 

program execution is transferred to the line 
specified by the ON ERROR statement. 

An error trapping routine should check for all the 
particular errors that the user wishes to recover 
from, and should specify the course of action to be 
taken in each case. 

This either involves correcting the error, and resum¬ 
ing execution at a specified statement or, return¬ 
ing to Command Level. 

an event occurs and 
the corresponding 
event trapping is 
enabled (programmed 
interrupt) 

program execution is transferred to the line 
specified by the ON event GOSUB statement. An 
event trapping routine should specify the course of 
action to be taken in this case. The events that can 
be trapped are: receipt of characters from a com¬ 
munications port; detection of certain keystrokes; 
time passage; or emptying of the background music 
buffer.See Chapter 6 (“Event Trapping”) for further 
details. 


Example 

10 ON ERROR GOTO 100 
20 INPUT ’’WHAT IS YOUR BET”; B 
30 IF B > 5000 THEN ERROR 200 


100 IF ERR = 200 THEN PRINT ’’HOUSE LIMIT IS $5000” 
110 IF ERL = 30 THEN RESUME 20 
120 ON ERROR GOTO 0 

















If you enter a value of B>5000, the message: 

HOUSE LIMIT IS $5000 

is displayed and execution resumes at line 20. 

Statement 10 (ON ERROR GOTO 100) both enables error trapping 
and transfers control to line 100 if an error occurs. The statement ER¬ 
ROR 200 at line 30 generates the user defined error 200. When this 
statement is executed control is transferred to line 100. 

At statement 120, ON ERROR GOTO 0 disables error trapping, thus 
if any error is encountered other than error 200 the standard error 
message will be displayed. 

Note the meaning of the special built-in functions ERR and ERL. The 
former contains the error code, the latter the line number of the line 
where the error occurs. 
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CONSTANTS 

Constants are the values that GW-BASIC uses during program execu¬ 
tion. There are two types of constant: string and numeric. 

A string constant is a sequence of up to 255 alphanumeric characters 
enclosed in double quotation marks. 

Examples: 

’’READY” 

”$80” 

’’acceleration rate” 

Numeric constants are positive or negative numbers. GW-BASIC 
numeric constants cannot contain commas. There are five types of 
numeric constant: 

1. Integer constants 

Whole numbers between -32768 and 32767. Integer constants do 
not contain decimal points. 

2. Fixed-point constants 

Positive or negative real numbers, i.e., numbers that contain 
decimal points. 

3. Floating-point constants 

Positive or negative numbers represented in exponential form 
(similar to scientific notation). A floating-point constant consists 
of an optionally signed integer or fixed-point number (the mantissa) 
followed by the letter E and an optionally signed integer (the ex¬ 
ponent). The range for floating-point constants is 10E-38 to 10E + 38. 

Examples: 

235.988E-7 is equivalent to .0000235988 
2359E6 is equivalent to 2359000000 

(Double precision floating-point constants are denoted by the let¬ 
ter D instead of E. See later in this chapter.) 










4. Hex constants 

Hexadecimal numbers denoted by the prefix &H. 

Examples: 

&H76 

&H32F 

&HFFAA 

5. Octal constants 

Octal numbers denoted by the prefix &0 or &. 

Examples: 

&0347 

&1234 


SINGLE AND DOUBLE PRECISION FORM FOR NUMERIC 
CONSTANTS 

Numeric constants may be either single precision or double precision 
numbers. Single precision numeric constants are stored with 7 digits 
of precision, and printed with up to 7 digits of precision. Double preci¬ 
sion numeric constants are stored with 16 digits of precision and printed 
with up to 16 digits. 

A single precision constant is any numeric constant that has one of 
the following characteristics: 

1. Seven or fewer digits. 

2. Exponential form using E. 

3. A trailing exclamation point (!). 


Examples: 

46.8 

-1.09E-06 

3489.0 

22.5! 
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A double precision constant is any numeric constant that has one of 
the following characteristics: 

1 . Eight or more digits. 

2. Exponential form using D. 

3. A trailing number sign (#). 

Examples: 


345692811 
-1.09432D-06 
3489.0# 
7654321.1234 


VARIABLES 

Variables are names used to represent values used in a GW-BASIC 
program. The value of a variable may be assigned explicitly by the 
programmer, or it may be assigned as the result of calculations in the 
program. Before a variable is assigned a value, its value is assumed 
to be zero. 


VARIABLE NAMES AND DECLARATION CHARACTERS 

GW-BASIC variable names may be any length. Up to 40 characters 
are significant. Variable names can contain letters, numbers, and the 
decimal point. However, the first character must be a letter. Special 
type declaration characters are also allowed (see below). 

A variable name may not be a reserved word, but embedded reserv¬ 
ed words are allowed. Reserved words include all GW-BASIC com¬ 
mands, statements, function names, and operator names. If a variable 
begins with FN, it is assumed to be a call to a user-defined function. 






Variables may represent either a numeric value or a string. String 
variable names are written with a dollar sign ($) as the last character. 
For example: A$ = ’’SALES REPORT”. The dollar sign is a variable 
type declaration character; that is, it ’’declares” that the variable will 
represent a string. 

Numeric variable names may declare integer, single precision, or dou- 
bie precision values. The type declaration characters for these variable 
names are as follows: 

% Integer variable 

! Single precision variable 

# Double precision variable 

The default type for a numeric variable name is single precision. 
Examples of GW-BASIC variable names: 


PI# 

Declares a double precision value. 

MINIMUM! 

Declares a single precision value. 

LIMIT% 

Declares an integer value. 

N$ 

Declares a string value. 

ABC 

Declares a single precision value. 


There is a second method by which variable types may be declared. 
The GW-BASIC statements DEFINT, DEFSTR, DEFSNG, and 
DEFDBL may be included in a program to declare the types for cer¬ 
tain variable names. These statements are described in detail in 
Chapter 8. 
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ARRAY VARIABLES 

An array is a group or table of values referenced by the same variable 
name. Each element in an array is referenced by an array variable that 
is subscripted with an integer or an integer expression. An array 
variable name has as many subscripts as there are dimensions in the 
array. For example V(10) would reference a value in a one-dimension 
array, T(1,4) would reference a value in a two-dimension array, and 
so on. The maximum number of dimensions for an array is 255. The 
maximum number of elements per dimension is 32,767. Both these 
values are also limited by the memory size of your system. 

In the interest of brevity, whenever a specific parameter is referred 
to as a variable in the syntax of a statement or command, no distinc¬ 
tion is made as to whether it is a simple variable or an array element. 


MEMORY REQUIREMENTS 

The number of bytes required by strings, variables and arrays is listed 
below. 


Variable Type Bytes 

Integer 2 

Single Precision 4 

Double Precision 8 


Array Type Bytes 


Integer 2 per element 

Single Precision 4 per element 

Double Precision 8 per element 

Strings 


3 bytes overhead plus the contents of the string. 








TYPE CONVERSION 

When necessary, GW-BASIC will convert a numeric constant from one 
type to another. The following rules and examples should be observed. 

1. If a numeric constant of one type is set equal to a numeric variable 
of a different type, the number will be stored as the type declared 
in the variable name. (If a string variable is set equal to a numeric 
value or vice versa, a ’’Type mismatch” error occurs.) 

Example: 

10 A% = 23.42 
20 PRINT A% 

RUN 

23 

2. During expression evaluation, all of the operands in an arithmetic 
or relational operation are converted to the same degree of preci¬ 
sion, i.e., that of the most precise operand. Also, the result of an 
arithmetic operation is returned to this degree of precision. 

Example: 

10 D# =6#/7 
20 PRINT D# 

RUN 

.8571428571428571 

The arithmetic is performed in double precision and the result is 
returned in D# as a double precision value. 

Example: 


10 D = 6#/7 
20 PRINT D 

RUN 

.8571429 

The arithmetic is performed in double precision and the result is 
returned to D (single precision variable), rounded, and printed as 
a single precision value. 
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3. Logical operators convert their operands to integers and return 
an integer result. Operands must be in the range -32768 to 32767 
or an ’’Overflow” error occurs. A full description of Loqical 
Operators follows later in this chapter. 

4. When a floating-point value is converted to an inteqer, the frac¬ 
tional portion is rounded. 

Example: 

10 C% = 55.88 
20 PRINT C% 

RUN 

56 

5. If a double precision variable is assigned a single precision value, 
only the first seven digits (rounded) of the converted number will 
be valid. This is because only seven digits of accuracy were sup¬ 
plied with the single precision value. The absolute value of the 
difference between the printed double precision number and the 
original single precision value will be less than 6.3E-8 times the 
original single precision value. 

Example: 


10 A = 2.04 
20 B# = A 
30 PRINT A;B# 

RUN 

2.04 2.039999961853027 







EXPRESSIONS AND OPERATORS 

An expression may be a string or numeric constant, a variable, or a 
combination of constants and variables with operators. An expression 
always produces a single value. 

Operators perform mathematical or logical operations on values. The 
GW-BASIC operators may be divided into four categories: 

1. Arithmetic 

2. Relational 

3. Logical 

4. Functional 

Each category is described in the following subsections. 

ARITHMETIC OPERATORS 

The arithmetic operators, in order of precedence, are as follows: 


OPERATOR 

OPERATION 

SAMPLE EXPRESSION 

A 

Exponentiation 

X A Y 

- 

Negation 

-X 

* , / 

Multiplication, Floatingpoint 

X*Y 


Division 

X/Y 

\ 

Integer Division 

X\Y 

MOD 

Modulus Arithmetic 

X MOD Y 

+ 

Addition, Subtraction 

X + Y, X-Y 


Tab. 3-1 Arithmetic Operators 
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Jioe£c n n e the . order In which the operations are performed, use paren¬ 
theses Operations within parentheses are performed first. Within the 
parentheses, the usual order of operations is maintained. 

BASIC^unterpads' 3 ' 0 expressions follow - together with their GW- 


Algebraic Expression 
X + 2Y 
Y 

X- 

Z 

XY 

~T 

X + Y 


GW-BASIC Expression 
X + Y*2 
X-Y/Z 

X*Y/Z 

(X + Y)/Z 


2 

(X) 


X 

X(-Y) 


(X a 2) a Y 
X a (Y a Z) 
X*(-Y) 


Note 


IZ C nTnTx ? (-?re?ample mUSt * S6para,ed by paren,heses ' a = 







INTEGER DIVISION AND MODULUS ARITHMETIC 

Two additional operators are available in GW-BASIC: integer division 
and modulus arithmetic. 

Integer division is denoted by the backslash (\). The operands are 
rounded to integers before the division is performed, and the quotient 
is truncated to an integer. The operands must be within the range 
-32768 to 32767. 


Example 

10\4 is 2 
25.68\6.99 is 3 

Integer division follows multiplication and floating-point division in order 
of precedence. 

Modulus arithmetic is denoted by the operator MOD. Modulus 
arithmetic yields the integer value that is the remainder of an integer 
division. 

Example 

10.4 MOD 4 is 2 (10/4 = 2 with a remainder 2) 

25.68 MOD 6.99 is 5 (26/7 = 3 with a remainder 5) 

Modulus arithmetic follows integer division in order of precedence. 


OVERFLOW 

If, during the evaluation of an expression, division by zero is en¬ 
countered, the ’’Division by zero” error message is displayed, machine 
infinity (the largest number that can be represented in floating-point 
format) with the sign of the numerator is supplied as the result of the 
division, and execution continues. If the evaluation of an exponentia¬ 
tion operator results in zero being raised to a negative power, the "Divi¬ 
sion by zero” error message again is displayed, positive machine 
infinity is supplied as the result of the exponentiation, and execution 
continues. 
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If overflow occurs, the ’’Overflow” error message is displayed machine 
e^e^u^tion^cotftinues!" 310311 ^ Si9n * SUppHed aS the rasult ’ and 


RELATIONAL OPERATORS 

Relational operators are used to compare two values The result of 

SK either "true” <-1,or ■■false" (0). This resuh ma y U ,l!e°„' 
oe used to make a decision regarding program flow. 

The relational operators are: 


OPERATOR 

RELATION TESTED 

EXAMPLE 

= 

Equality 

X = Y 

< > 

(or ><) 

Inequality 

XoY 

< 

Less than 

X<Y 

> 

Greater than 

X> Y 

< = 

(or = <) 

Less than or equal to 

> 

11 

V 

X 

> = 

(or = >) 

ToM O o 

Greater than or equal to 

> 

II 

A 

X 


Tab. 3-2 Relational Operators 


is also used to assign a value to a variable. See the 
LET Statement in Chapter 8.) 












When arithmetic and relational operators are combined in one expres¬ 
sion, the arithmetic operation is always performed first. For example, 
the expression: 

X + Y<(T-1)/Z 

is true if the value of X plus Y is less than the value of (T-1)/Z. 

More examples: 

IF SIN(X)<0 GOTO 1000 
IF I MOD JoO THEN K = K + 1 


LOGICAL OPERATORS 

Logical operators perform tests on multiple relations, bit manipulation, 
or Boolean operations. The logical operator returns a result which is 
either ’’true” (not zero) or ’’false” (zero). In an expression, logical 
operations are performed after arithmetic and relational operations. 
The outcome of a logical operation is determined as shown in Figure 
3-3. 

The operators are listed in order of precedence. 
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NOT 

X NOT X 


1 0 
0 1 


AND 

X Y X AND Y 


1 1 1 
1 0 0 
0 1 0 
0 0 0 


OR 

X Y X OR Y 


1 1 1 

1 0 1 

0 1 1 

0 0 0 

__ ► 


Fig. 3-3 GW-BASIC Logical Operators Truth Table 













XOR 


X 

Y 

X XOR Y 


1 

1 

0 


1 

0 

1 


0 

1 

1 


0 

0 

0 

EQV 


X 

Y 

X EQV Y 


1 

1 

1 


1 

0 

0 


0 

1 

0 


0 

0 

1 

IMP 


X 

Y 

X IMP Y 


1 

1 

1 


1 

0 

0 


0 

1 

1 


0 

0 

1 


Fig. 3-3 GW-BASIC Logical Operators Truth Table (cont.) 


Just as the relational operators can be used to make decisions regar¬ 
ding program flow, logical operators can connect two or more relations 
and return a true or false value to be used in a subsequent decision. 

Examples 

IF D<200 AND F<4 THEN 80 
IF l> 10 OR K<0 THEN 50 
IF NOT P THEN 100 
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Logical operators work by converting their operands to 16-bit, signed, 
two’s complement integers in the range -32768 to 32767, (if the 
operands are not in this range, an error results). If both operands are 
supplied as 0 or -1, logical operators return 0 or -1. The given opera¬ 
tion is performed on these integers bit-by-bit, i.e., each bit of the result 
is determined by the corresponding bits in the two operands. 

Thus, it is possible to use logical operators to test bytes fora particular 
bit pattern. For instance, the AND operator may be used to ’’mask” 
all but one of the bits of a status byte at a machine I/O port. The OR 
operator may be used to ’’merge” two bytes to create a particular 
binary value. The following examples will help demonstrate how the 
logical operators work. 


63 AND 16= 16 


15 AND 14= 14 


-1 AND 8 = 8 


4 OR 2 = 6 


10 OR 10 = 10 


the result is 16, as 
63 = binary 111111 
16 = binary 010000 
010000 

the result is 14, as 
15 = binary 1111 
14 = binary 1110 
1110 

the result is 8, as 
-1 = binary 1111111111111111 
8 = binary OOOOOOOOOOOOIQOO 
0000000000001000 

the result is 6, as 
4 = binary 100 
2 = binary _J_0 

110 

the result is 10, as 
10 = binary 1010 
10 = binary 1010 


1010 











-1 OR -2 = -1 the result is -1, as 

-1 = binary 1111111111111111 
-2 = binary 1111111111111110 
1111111111111111 


NOT X = -(X +1) The two’s complement of any integer is the 
bit complement plus one. 


11111100110011000 original value (negative) 


inverting all the bits: 


0000011001100111 inverted value 


adding 1: 


0000011001101000 absolute value 

(inverted + 1) 


so the value in decimal of the given pattern is: 
1 640 
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FUNCTIONAL OPERATORS 

When a function is used in an expression, it calls a predetermined 
operation that is to be performed on an operand. GW-BASIC has ’’in¬ 
trinsic” functions that reside in the system, such as SQR (square root) 
or SIN (sine). All GW-BASIC intrinsic functions are described in Chapter 

GW-BASIC also allows ’’user-defined” functions that are written by 
the programmer. (See ”DEF FN” Statement in Chapter 8.) 


STRING OPERATORS 

Strings may be concatenated by using +. 


Example 


10 A$ = ”FILE” : B$= ’’NAME” 

20 PRINT A$ + B$ 

30 PRINT ’’NEW ” + A$ + B$ 

RUN 

FILENAME 
NEW FILENAME 

Strings may be compared using the same relational operators that are 
used with numbers: 

= <><>< =(or = <) > = (or = >) 

String comparisons are made by taking one character at a time from 
each string and comparing the ASCII codes. If all the ASCII codes are 
the same, the strings are equal. If the ASCII codes differ, the lower 
code number precedes the higher. If during string comparison the end 
of one string is reached, the shorter string is said to be smaller. Leading 
and trailing blanks are significant. 






Examples 


”AA”<”AB” 

"FILENAME” =’’FILENAME” 

”X&”>”X#” 

”CL ”>”CL” 

”kg”>”KG” 

"SMYTH” <”SMYTHE” 

B $< ”9/12/78” where B$= ”8/12/78” 

Thus, string comparisons can be used to test string values or to 
alphabetize strings. All string constants used in comparison expres¬ 
sions must be enclosed in quotation marks. 
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INTRODUCTION 

Disk input and output procedures for the GW-BASIC user are examin¬ 
ed in this chapter. If you are new to GW-BASIC or if you are getting 
disk-related errors, read through these procedures and program ex¬ 
amples to make sure you are using all the disk statements correctly. 

Wherever a filename is required in a disk command or statement, use 
a name that conforms to the filenaming conventions for your operating 
system. The MS-DOS operating system will append a default exten¬ 
sion .BAS to the filename given in a SAVE, RUN, MERGE or LOAD 
command. 


DEVICE INDEPENDENT INPUT/OUTPUT 


GW-BASIC provides device-independent input/output; using device in¬ 
dependent I/O means that the syntax for access is the same for any 
device. 

The following statements, commands, and functions support device¬ 
independent I/O: 


BLOAD 

LOF 

BSAVE 

MERGE 

CHAIN 

OPEN 

CLOSE 

POS 

EOF 

PRINT# 

GET 

PRINT# USING 

INPUT# 

PUT 

INPUT$ 

RUN 

LINE INPUT# 

SAVE 

LIST 

WIDTH 

LOAD 

WRITE# 

LOC 



HOW MS-DOS KEEPS TRACK OF YOUR FILES 

A file is a collection of records. The names of files are kept in direc¬ 
tories on disk or diskette. These directories also contain information 
on the size of the files, their location on the disk, and the dates that 
they were created and updated. The directory you are working in is 
called your current directory. 






An additional system area is called the File Allocation Table. It keeps 
track of the location of your files on the disk. It also allocates the free 
space on your disks so that you can create new files. 

These two system areas, the directories and the File Allocation Table, 
enable MS-DOS to recognize and organize the files on your disks. The 
File Allocation Table is created onto a new disk when you format it 
with the MS-DOS FORMAT command, and one empty directory is 
created, known as the ’’root” directory. 

To use the information you must OPEN the file to tell GW-BASIC where 
the information is. You may then use the file for input and/or output. 


FILE NUMBERS 

The maximum number of files that can be simultaneously opened is 
set by the IF: option in the GWBASIC command. A file number is 
associated with a file when the file is opened and it is used by any 
subsequent I/O statement to refer to the file (see the GWBASIC com¬ 
mand and the OPEN statement in Chapter 8). 


NAMING FILES 

File specifications follow MS-DOS naming conventions. The 
filespec is a string expression with the following format: 

[ device: ] filename 

All file specifications may begin with a device specification such as 
A: or B: or COM1: or LPT 1:. If no device is specified, the current drive 
is assumed. 

A filename can comprise: 

• one to eight characters (for legal characters see below). For exam¬ 
ple NEWFILE. 

• one to eight characters, followed by a period (.) and a one to three 
character file name extension. For example NEWFILE.EXE. 
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A filename may be made up of any of the following characters: 

A-Z 0-9 $ & # 

%’()-- 
@ a ( ) ! 

Alphabetic characters within the file name can be entered in upper 
or lower case, but MS-DOS will translate lower case letters into upper 
case. The extension .BAS is supplied if no extension is given, but 
NAME and KILL do not follow this rule: they do not supply any ex¬ 
tension. 


Note 

File specification for communications devices is slightly different. The 
filename is replaced with a list of options specifying such things as 
line speed. Refer to the OPEN COM statement in Chapter 8 for details. 

Remember that if you use a string constant for the file specification, 
you must enclose it in quotation marks. The only exception to this rule 
is the GWBASIC command, where a file specifier is a string constant 
not included in quotation marks. 

For example: 

LOAD ”B:ARSENAL.RED” 

For example: 

GWBASIC PAYROLL 


NAMING DEVICES 

The device name is a string of four characters or less followed by a 
colon (:), and may be one of the following: 


A: first diskette drive 
B: second diskette drive 
C: first hard disk drive 


(Any access mode) 
(Any access mode) 
(Any access mode) 





D: second hard disk drive 
KYBD: keyboard 
SCRN: screen 
LPT1: first printer 
LPT2: second printer 
LPT3: third printer 
COM1: RS232 Port 1 
COM2: RS232 Port 2 


(Any access mode) 
(Input only) 


(Output only) 


(Output or random) 
(Output or random) 
(Output or random) 
(Input and Output) 
(Input and Output) 


DIRECTORY PATHS 

With GW-BASIC the user can organize a disk in such a manner that 
files that are not part of his current task do not interfere with that task. 

Previously, only a single directory was supported that contained all 
the files on a disk. MS-DOS extends this concept to allow a directory 
to contain both files and directories and to introduce the notion of the 
current directory. 

To specify a file, the user could use one of two methods, either specify 
a path from the root directory to the file, or specify a path from the 
current directory to the file. A’’Directory Path” (or pathname ) is 
a series of directory names separated by V and ending with a file 
name. A pathname that starts at the root begins with the V. 

There are two special directory entries in each directory, denoted by 
’.’ and They specify the directory itself (’.’) or the parent of the direc¬ 
tory (’..’). The root directory’s parent is itself. 
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Let us take a hypothetical example. 


In a particular business, both sales and accounting share a computer 
with a large disk and the individual employees use it for preparation 
of reports and maintaining accounting information. One would naturally 
view the organization of files on the disk in this fashion: 



SALES ACCOUNTS 



Fig. 4-1 Disk File Organization 


Using a directory structure like the hierarchy above, and assuming that 
the current directory is directory JOHN, to reference the REPORT 
under JOHN, the following are equivalent: 

REPORT 

\SALES\JOHN\REPORT 

To refer to the REPORT under MARY, supposing that JOHN is still 
the current directory, the following are equivalent: 

..\MARY\REPORT 

\SALES\MARY\REPORT 
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To refer to the REPORT under SUE, supposing that JOHN is still the 
current directory, the following are equivalent: 

..\..\ACCOUNTS\SUE\REPORT 

\ACCOUNTS\SUE\REPORT 

There is no restriction on the depth of a tree (the length of the longest 
path from root to leaf). 

The root directory will have a fixed maximum number of entries for 
a diskette. There is no limit to the number of files and/or subdirectories 
in the root directory of a hard disk, other than the size of the MS-DOS 
partition (see the ’’MS-DOS User Guide”). 

Other ’’sub-directories” can also be accessed via the root directory, 
and these in turn can branch off to further files and sub-directories. 
The only limit being the space available on the disk. 

Each directory can also contain file and directory names that also ap¬ 
pear in other directories. 

Pathnames can be used for the following commands: 


BLOAD 

GWBASICO 

NAME 

BSAVE 

KILL 

OPEN 

CHAIN 

LOAD 

RMDIR 

CHDIR 

MERGE 

RUN 

FILES 

MKDIR 

SAVE 


(*) Used to initialize GW-BASIC. This is an MS-DOS command (not 
a GW-BASIC command). 

A pathname may be considered as an extension of filespec and 
is a string expression of the form: 

[ device: ][ \][ directory ][ \directory ]...[ \ ] filename 

or 

[ device: ][ \][ directory ][ \directory ]...[ directory ] [ \] 

All characters that are valid for a filename are also valid for a directory 
name. 
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Examples (supposing JOHN is the current directory): 

B:\SALES\MARY\REPORT 
B:..\MARY\REPORT is equivalent 

Note 

A pathname may not contain more than 63 characters. Pathnames 
longer than 63 characters will give a ’’Bad Filename” error. 

Specifying a pathname where only a filespec is legal, or plac- 
mg a device other than at the beginning of the pathname will 
result in a Bad Filename” error. 

If you use a string constant for the pathname , you must enclose 
it in quotation marks. The GWBASIC command only specifies 
pathnames as literal strings not included in quotation marks. 


CURRENT DIRECTORY 

If you enter a filename , in a GW-BASIC statement or command 
without specifying a directory, the ’’current directory” is searched. A 
single directory is created on a disk when it is formatted. That direc¬ 
tory, * s the root directory, and it is the current directory, in¬ 
itially. You can create other directories by entering the MKDIR 
command or remove directories by entering the RMDIR command, 
he CHDIR command allows you to change the current directory. 

If a pathname begins with a backslash (\), GW-BASIC starts its 
search from the ’’root”; otherwise it starts its search from the current 
directory. The pathname you specify can be either a sequence of 
d' r ® ct ° r y names starting with the ’’root”, or with the current directory 
If the file belongs to the current directory you only need to specify the 


COMMANDS FOR PROGRAM FILES 

The following list reviews the commands and statements used in pro¬ 
gram file manipulation. H 


With GW-BASIC the asterisk (*) and question mark (?) can be used 
as wild cards with the FILES and KILL commands. 






SYNTAX 

MEANING 


SAVE filespec 
[,[A|P)1 

or 

SAVE pathname 
[,{A|Pj] 

Writes to disk the program that currently resides in 
memory. Option A writes the program as a series 
of ASCII characters (otherwise, GW-BASIC uses a 
compressed binary format); option P writes the pro¬ 
gram in a protected form. (See ’’Protected Files in 
this chapter). 

LOAD filespec [,R] 

or 

LOAD pathname [,R] 

Loads the program from disk into memory. Option 

R runs the program immediately. LOAD always 
deletes the current contents of memory and closes 
all files before loading. If R is included, however, 
open data files are kept open. Thus, programs may 
be chained or loaded in sections and access the 
same data files. LOAD filespec , R and RUN filespec, 
R are equivalent. 

RUN filespecl R] 

or 

RUN pathname [,R] 

RUN filespec loads the program from disk into 
memory and runs it. RUN deletes the current con¬ 
tents of memory and closes all files before loading 
the program. If the R option is included however, all 
open data files are kept open. 

MERGE filespec 

or 

MERGE pathname 

Loads the program from disk into memory but does 
not delete the current contents of memory. The pro¬ 
gram line numbers on disk merge with the line 
numbers in memory. If two lines have the same 
number, only the line from the disk program is sav¬ 
ed. After a MERGE command, the ’’merged” pro¬ 
gram resides in memory, and GW-BASIC returns to 
command level. 
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SYNTAX 

MEANING 

KILL filespec 
or 

KILL pathname 

Deletes the file from the disk. The file may be a pro¬ 
gram file, or a sequential or random access data file. 

NAME [filespec | 
pathname! AS 
filename 

Changes the name of a disk file. NAME may be us¬ 
ed with any disk file. 


PROTECTED FILES 

If you want to save a program in an encoded binary format, use the 
P option with the SAVE command. For example: 

SAVE ”MYPROG”,P 

Note 

Because a program saved in this manner cannot be listed or edited, 
you may want to save an unprotected copy of the program for this 
purpose. 


DISK DATA FILES - SEQUENTIAL AND RANDOM 
ACCESS 

Two types of disk data files can be created and accessed by a GW- 
BASIC program: 

• sequential files 


• random access files 











SEQUENTIAL FILES 


Sequential files are easier to create than random access files but limit 
flexibility and speed when accessing the data. The data written to a 
sequential file is in the form of ASCII characters which are loaded and 
stored, one item after another (sequentially), in the order they are sent. 

The statements and functions used with sequential files are as follows: 

CLOSE 

EOF 

INPUTS 

INPUT# 

LINE INPUT# 

LOC 

LOCK 

LOF 

OPEN 

PRINT# 

PRINT# USING 

UNLOCK 

WRITE# 

See Chapter 8 of this manual for more information on these statements 
and functions. 


CREATING A SEQUENTIAL FILE 

The following program steps are required to create a sequential file 
and access the data in the file: 

1. OPEN the file in ”0” mode: 

OPEN ”0”, # 1 ,”DATA” 


2. Write data to the file using the WRITE # statement (you may use 
the PRINT # statement instead): 

WRITE #1,A$;B$;C$ 
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3. To access the data in the file, you must CLOSE the file and 
reOPEN it in ”1” mode: 

CLOSE #1 

OPEN ”I”,#1,”DATA” 

4. Use the INPUT# statement to read data from the sequential file 
to the program: 

INPUT# 1,X$,Y$,Z$ 

A program that creates a sequential file can also write formatted data 
to the disk with the PRINT # USING statement. For example the 
statement: 

PRINT#1, USING”## # #. # # ,”;A,B,C,D 

could be used to write numeric data to disk without explicit delimiters. 
The comma (,) at the end of the format string serves to separate each 
item in the disk file. 


The LOC function, when used with a sequential file, returns the number 
of sectors that have been written to or read from the file since it was 
opened. For example: 

100 IF LOC(1)>50 THEN STOP 

would end program execution if more than 50 sectors had been writ¬ 
ten to, or read from, file #1 since it was opened. 

Program 1 is a short program that creates a sequential file, named 
DATA, from information you input at the terminal. 


10 OPEN ”0”,#1,”DATA” 

20 INPUT ”NAME”;N$ 

25 IF N$ = ’’DONE” THEN END 
30 INPUT ”DEPARTMENT”;D$ 

40 INPUT ’’DATE HIRED”;H$ 

50 PRINT#1,N$;”,”;D$;”,”;H$ 

60 PRINT:GOTO 20 

► 


Fig. 4-2 Program 1 - Create a Sequential Data File 










RUN 

NAME? MICKEY MOUSE 
DEPARTMENT? AUDIO/VISUAL AIDS 
DATE HIRED? 01/12/72 

NAME? SHERLOCK HOLMES 
DEPARTMENT? RESEARCH 
DATE HIRED? 12/03/65 

NAME? EBENEEZER SCROOGE 
DEPARTMENT? ACCOUNTING 
DATE HIRED? 04/27/78 


NAME? SUPER MAN 
DEPARTMENT? SECURITY 
DATE HIRED? 08/16/78 


NAME? etc. 

Fig. 4-2 Program 1 - Create a Sequential Data File (cont.) 

ACCESSING A SEQUENTIAL FILE 

Program 2 accesses the file ’’DATA” that was created in Program 1 
and displays the name of everyone hired in 1978. 


10 OPEN ”1”, # 1 ,”DATA” 

20 INPUT# 1,N$,D$,H$ 

30 IF RIGHT$(H$,2) = ”78” THEN PRINT 
40 GOTO 20 

RUN 

EBENEEZER SCROOGE 
SUPER MAN 
Input past end in 20 
Ok 


N$ 


Fig. 4-3 Program 2 - Access a Sequential File 

Program 2 reads, sequentially, every item in the file. When all the data 
has been read, line 20 causes an ’’Input past end” error. This error 
can be avoided, however, by inserting an additional line (line 15 shown 
below) which uses the EOF function to test for end-of-file. 
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15 IF E0F(1) THEN END 
Then change line 40 to GOTO 15. 


ADDING DATA TO A SEQUENTIAL FILE 

As soon as a sequential file is opened on disk in ”0” mode, its cur¬ 
rent contents are destroyed. In order to add more data to the file it 
is necessary to use the OPEN statement with the APPEND mode. 


RANDOM ACCESS FILES 

Creating and accessing random access files requires more program 
steps than with sequential files, but there are advantages to using ran¬ 
dom access files. Random access files require less room on the disk, 
because GW-BASIC stores them in a packed binary format. (A sequen¬ 
tial file is stored as a series of ASCII characters.) 


The biggest advantage to random access files is that data can be ac¬ 
cessed at random, i.e., anywhere on the disk. It is not necessary to 
read through all the information on disk with random access files, as 
with sequential files. This is possible because the information is stored 
and accessed in distinct units called records and each record has an 
identification number. 


The statements and functions that are used with random access files 
are: 


CLOSE 

CVD 

CVI 

CVS 

FIELD 

GET 

LOC 

LOCK 

LOF 

LSET 

MKD$ 

MKI$ 

MKS$ 

OPEN 

PUT 

RSET 

UNLOCK 
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CREATING A RANDOM ACCESS FILE 

Creation of a random access file requires the following program steps. 

1 OPEN the file for random access (”R” mode). This example 
specifies a record length of 32 bytes. If the record length is omit¬ 
ted, the default is 128 bytes. 

OPEN ”R”, # 1,’’FILE”,32 

2. Use the FIELD statement to allocate space in the random buffer 
for the variables that will be written to the random file. 

FIELD# 1,20 AS N$, 4 AS A$,8 AS P$ 

3. Use the LSET command to move the data into the random buffer. 
Numeric values must be made into strings when placed in the buf¬ 
fer To do this, use the ’’make” functions.MKIS converts an integer 
into a string, MKS$ converts a single precision number into a 
string, and MKD$ converts a double precision number into a string. 

LSET N$ = X$ 

LSET A$ = MKS$(AMT) 

LSET P$ = TEL$ 

4. Write the data from the buffer to the disk using the PUT statement. 

PUT # 1 ,CODE% 

The LOC function, with random access files, returns the ’’current record 
number”. The current record number is one plus the last record 
number that was used in a GET or PUT statement. For example, the 
statement 

IF LOC(1) > 50 THEN END 

ends program execution if the current record number in file # 1 is higher 
than 50. 

Program 3 writes information that is input at the terminal to a random 
access file. 
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10 OPEN ”R”,#1,”FILE”,32 
20 FIELD #1,20 AS N$, 4 AS A$, 8 AS 
30 INPUT ’’2-DIGIT CODE”;CODEo/ 0 
40 INPUT ”NAME”;X$ 

50 INPUT ”AMOUNT”;AMT 
60 INPUT ”PHONE”;TEL$:PRINT 
70 LSET N$ = X$ 

80 LSET A$ = MKS$(AMT) 

90 LSET P$ = TEL$ 

100 PUT # 1,CODE°/o 
110 GOTO 30 


P$ 


Fig. 4-4 Program 3 - Create a Random Access File 


Each time the PUT statement is executed, a record is written to the 
file. The two-digit code that is input in line 30 becomes the record 
number. 


Warning 

Do not use a FIELDed string variable in an INPUT or LET statement. 
This causes the pointer for that variable to point into string space in¬ 
stead of into the random access file buffer. 


ACCESSING A RANDOM ACCESS FILE 

Creation of a random access file requires the following steps. 
1. OPEN the file in ”R” mode: 

OPEN ”R”, # 1,’’FILE”,32 










2 Use the FIELD statement to allocate space in the random buffer 
for the variables that will be read from the file: 

FIELD # 1,20 AS N$, 4 AS A$,8 AS P$ 

Note 

In a program that performs both input and output on the same ran¬ 
dom file, you can often use just one OPEN statement and one 
FIELD statement. 

3. Use the GET statement to move the desired record into the ran¬ 
dom buffer: 

GET # 1 ,CODE% 

4 The data in the buffer may now be accessed by the program. 
Numeric values that are read in from a random file buffer must 
be converted from strings back into numbers using the ’’convert 
functions. CVI converts a 2-byte string to an integer, CVS con¬ 
verts a 4-byte string to a single precision number, and CVD con¬ 
verts an 8-byte string to a double precision number: 


PRINT N$ 

PRINT CVS(A$) 

Program 4 accesses the random access file ’’FILE” that was created 
in Program 3. When the two-digit code is entered at the terminal, the 
information associated with that code is read from the file and 
displayed. 


10 OPEN ”R”,#1,”FILE”,32 

20 FIELD #1, 20 AS N$, 4 AS A$, 8 AS P$ 

30 INPUT ’’2-DIGIT CODE”;CODE% 

40 GET #1, CODE°/o 
50 PRINT N$ 

60 PRINT USING ”$$# # #.# #”;CVS(A$) 

70 PRINT P$:PRINT 
80 GOTO 30 

Fig. 4-5 Program 4 - Access a Random Access File 
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Program 5 is an inventory program that illustrates random file access 
In this program, the record number is used as the part number, and 
it is assumed the inventory will contain no more than 100 different part 
numbers. Lines 900 through 960 initialize the data file by writing 
CHR$(255) as the first character of each record. This is used later (line 
270 and line 500) to determine whether an entry already exists for that 
part number. 

Lines 140 through 210 display the different inventory functions that 
the program performs. When you type in the desired function number, 
line 230 branches to the appropriate subroutine. 


120 OPEN”R”, # 1,’’INVEN.DAT”,39 

130 FIELD#1,1 AS F$,30 AS D$,2 AS Q$,2 AS R$,4 AS P$ 

140 PRINT:PRINT ”FUNCTIONS:”:PRINT 
150 PRINT 1,’’INITIALIZE FILE” 

160 PRINT 2,’’CREATE A NEW ENTRY” 

170 PRINT 3,’’DISPLAY INVENTORY FOR ONE PART” 

180 PRINT 4,’’ADD TO STOCK” 

190 PRINT 5,’’SUBTRACT FROM STOCK” 

200 PRINT 6,’’DISPLAY ALL ITEMS BELOW REORDER LEVEL” 
210 PRINT:PRINT:INPUT”FUNCTION”;FUNCTION 
220 IF (FUNCTION<1)OR(FUNCTION>6) THEN PRINT ’’BAD 
FUNCTION NUMBER”:GOTO 140 
230 ON FUNCTION GOSUB 900,250,390,480,560,680 
240 GOTO 210 

250 REM BUILD NEW ENTRY 
260 GOSUB 840 


270 IF ASC(F$)< >255 THEN INPUT”OVERWRITE” A$- IF 
A$< >”Y” THEN RETURN 
280 LSET F$ = CHR$(0) 

290 INPUT ”DESCRIPTION”;DESC$ 

300 LSET D$ = DESC$ 

310 INPUT ’’QUANTITY IN STOCK” Q% 

320 LSET Q = MKI$(Q%) 

330 INPUT ’’REORDER LEVEL”;R% 

340 LSET R$ = MKI$(R%) 

350 INPUT ’’UNIT PRICE”;P 
360 LSET P$ = MKS$(P) 

370 PUT #1,PART% 


► 


Fig. 4-6 Program 5 - Inventory 










480 

490 

500 

510 


380 RETURN 

390 REM DISPLAY ENTRY 

410 F^ASC(F$) = 255 THEN PRINT ’’NULL ENTRY”:RETURN 
420 PRINT USING ’’PART NUMBER # # #”;PART°/o 
430 PRINT D$ „ 

440 PRINT USING ’’QUANTITY ON HAND ##### ;CVI(Q$) 
450 PRINT USING ’’REORDER LEVEL # # # # #”;CVI(R$) 

460 PRINT USING ’’UNIT PRICE $$##.# #”;CVS(P$) 

470 RETURN 

REM ADD TO STOCK 
GOSUB 840 

IF ASC(F$) = 255 THEN PRINT ’’NULL ENTRY”:RETURN 
PRINT D$:INPUT ’’QUANTITY TO ADD ”;A% 

520 Q% = CVI(Q$) + A% 

530 LSET Q$ = MKI$(Q%) 

540 PUT#1,PART°/o 
550 RETURN 

560 REM REMOVE FROM STOCK 
570 GOSUB 840 

580 IF ASC(F$) = 255 THEN PRINT ’’NULL ENTRY”:RETURN 
590 PRINT D$ 

600 INPUT ’’QUANTITY TO SUBTRACT”;S% 

610 Q°/o = CVI(Q$) 

620 IF (Q%-S%)<0 THEN PRINT ”ONLY”;Q%;” IN STOCK”:GOTO 
600 

640 IF^o/o^CVKRS) THEN PRINT ’’QUANTITY NOW”;Q°/o; ” 
REORDER LEVEL” ;CVI(R$) 

650 LSET Q$ = MKI$(Q%) 

660 PUT #1,PART°/o 
RETURN 

REM DISPLAY ITEMS BELOW REORDER LEVEL 
FOR 1 = 1 TO 100 
GET # 1 I 

720 IF CVI(Q$)<CVI(R$) THEN PRINT D$;” QUANTITY”; CVI(Q$) 
TAB(50) ’’REORDER LEVEL”;CVI(R$) 

NEXT I 
RETURN 

INPUT ’’PART NUMBER”;PART% 


670 

680 

690 

710 


730 

740 

840 


Fig. 4-6 Program 5 - Inventory (cont.) 
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850 IF(PART% < 1 )OR(PART°/o> 100) THEN PRINT ’’BAD PART 
NUMBER”: GOTO 840 ELSE GET# 1,PART%:RETURN 
890 END 

900 REM INITIALIZE FILE 

910 INPUT ’’ARE YOU SURE”;B$:IF B$o”Y” THEN RETURN 
920 LSET F$ = CHR$(255) 

930 FOR 1 = 1 TO 100 
940 PUT# 1,1 
950 NEXT I 
960 RETURN 


Fig. 4-6 Program 5 - Inventory (cont.) 


FILE LOCKING 

There are three GW-BASIC statements that enable the user to control 
the access rights of disk files: OPEN, LOCK and UNLOCK. The LOCK 
and UNLOCK statements and the access parameter of OPEN can on¬ 
ly be used if MS-NET is installed with MS-DOS release 3.1 or later 
All three statements are fully described in Chapter 8. 
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ABOUT THIS CHAPTER 

GW-BASIC provides, under MS-DOS, a complete range of graphic 
features. The design of different shapes, using a range of colors holds 
a sizable amount of possibilities. The screen can be subdivided into 
rectangular sections, so that several different areas can be viewed at 
the same time. 

This chapter introduces screen graphics including screen modes, color 
use, coordinates, the statements VIEW and WINDOW, and other 
graphics statements. 
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HIHHI 


SELECTING THE GRAPHICS ENVIRONMENT 

The GW-BASIC language provides a set of graphics statements and 
functions which permit you to draw lines and points on the video us¬ 
ing various colors. You must select the graphics environment in order 
to use these statements. 

Upon initialization, the system is in Text Mode (SCREEN 0); you select 
the graphics environment using the SCREEN statement. 

There are three different graphics modes you can select: 

• Medium Resolution Mode (by entering SCREEN 1) 

• High Resolution Mode (by entering SCREEN 2) 

• Super Resolution Mode (by entering SCREEN 3) 

They differ in the number of points displayed and in the number of 
colors allowed. 


The SCREEN statement also allows you to select the “active” and 
the “visual” page, in text mode (using the apage and vpage 
parameters). The active page, is the page written to by subsequent 
output statements to the screen; the visual page is the one displayed 
on the screen. 

The SCREEN statement must precede any I/O statements to the 
screen. The system assumes SCREEN 0,0,0,0 by default; this selects 
80 columns Text Mode, and one display page. 

You can also use more than one SCREEN statement to define different 
screen attributes for different sections of your program. 

You can also change from one graphics mode to another by the WIDTH 
statement. The WIDTH statement allows you to set the screen width 
(in Text Mode) or change mode (in one of the graphics modes). 






TEXT MODE (SCREEN 0) 

In Text Mode you can display text, i.e. letters, numbers, and all special 
characters of the GW-BASIC character set. You can set the character 
foreground and background color using the COLOR statement. This 
statement also allows you to create blinking, reverse image, invisible, 
highlighted, and underscore characters. 

Characters are displayed in horizontal lines from top (line 1) to bottom 
(line 25). Each line has 40 (or 80) columns. The WIDTH command 
allows you to select the number of columns. 

The LOCATE statement positions the cursor on the screen. The cur¬ 
sor column and line coordinates are returned by the POS(O) and 
CSRLIN functions. 

Characters are usually displayed, using the PRINT or PRINT USING 
statements, at the cursor position from left to right on each line, from 
line 1 to 24. When the cursor passes to line 25, lines 1 to 24 are mov¬ 
ed one line up the screen. 

Line 25 will usually display the Function Key values (see KEY state¬ 
ment in Chapter 8). To move the cursor to line 25 and display 
characters, use KEY OFF, then LOCATE and PRINT statements. 


Multiple Display Page 

Multiple display pages are allowed in Text Mode. Every statement that 
reads or writes from the screen is actually reading/writing from or to 
the active page. The visual page is the page that is shown on the 
screen, and may be different from the active page. This feature allows 
you to display a page, while writing another. The active and visual 
pages may be selected by the SCREEN statement. 
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Statements and Functions 

The statements and functions available in Text Mode to display text are: 


STATEMENTS 

FUNCTIONS 

CLS 

CSRLIN 

COLOR 

POS 

LOCATE 

SCREEN 

PRINT 

SPC 

PRINT USING 

TAB 

SCREEN 


WIDTH 


WRITE 



In Text Mode you can select the character foreground and background 
colors, and make characters blink. 

If color hardware is installed, 16 different colors are available, specified 
by code: 


0 Black 

8 Gray 

1 Blue 

9 Light Blue 

2 Green 

10 Light Green 

3 Cyan 

11 Light Cyan 

4 Red 

12 Light Red 

5 Magenta 

13 Light Magenta 

6 Yellow 

14 Light Yellow 

7 White 

15 High-Intensity White 


In a monochrome system you can only use two colors (black and white), 
but you can also use shades of gray, underline characters, or display 
high-intensity characters. (See the COLOR (Text) statement in Chapter 
8, for details). 












GRAPHICS MODES 

In each of the three graphics modes you can still display text, but you 
can also draw complex pictures. 

To display text you can use all the statements, commands and func¬ 
tions available in Text Mode (the LOCATE and COLOR statements 
have different syntaxes for Text and Graphics). 

All points of the screen are addressable through their coordinates. A 
point on the screen is called a ’pixel’ (a contraction of ’’picture ele¬ 
ment”), and a line of pixels is called a ’’scanline”. 


Statements and Functions 

The statements and functions you can use in Graphics Mode to display 
pictures are: 


STATEMENT 

FUNCTIONS 

CIRCLE 

PMAP 

COLOR 

POINT 

DRAW 


GET (Graphics) 


LINE 


LOCATE 


PAINT 


PRESET 


PSET 


PUT (Graphics) 


SCREEN 


VIEW 


WINDOW 
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MEDIUM RESOLUTION MODE (SCREEN 1) 


In this mode, there are 320 pixels on the horizontal axis and 200 pix¬ 
els on the vertical axis. These are numbered from left to right and from 
top to bottom; thus the upper left corner pixel is (0,0) and the lower 
right corner pixel is (319, 199). 


You can display four colors at a time if a color monitor is used, other¬ 
wise the four colors will appear as shades of gray. 


Drawing Pictures 

When you draw pictures on the screen using the graphics statements 
(PSET, PRESET, LINE, CIRCLE, PAINT or DRAW), you can specify 
a color number of 0,1, 2, or 3. This selects the color from the current 
’’palette”. 


If you do not specify a color number in a graphics statement, the default 
is the graphics foreground specified by the COLOR statement, or 3 
(if no graphics foreground is given). 


The COLOR statement allows you to specify a palette. There are two 
palettes available, consisting of 4 colors, as shown in the followinq 
table: a 


PALETTE 

COLOR NUMBER 

0 

1 

2 

3 

0 

background 

green 

red 

yellow 

1 

background 

cyan 

magenta 

white 


Tab. 5-1 Palettes 
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Where background is the first parameter in the COLOR statement; it 
is specified as a color code and assigned to color number 0. It also 
specifies the background color for text. 

With a monocrome system, the use of memory is identical: the modes 
differ only in that the two bits of a pixel are interpreted differently by 
the hardware: 4 shades of gray are displayed. 


Displaying Characters 

The character foreground color is set by the 
tforeground parameter in the COLOR statement (default color 
number 3). The character background is set by the 
background parameter in the COLOR statement (default color 
number 0, i.e. black). 

If color is disabled the character foreground will be 1 (white) and the 
character background 0 (black). 

HIGH RESOLUTION MODE (SCREEN 2) 

In this mode, there are 640 pixels on the horizontal axis and 200 pix¬ 
els on the vertical axis. These are numbered from left to right and top 
to bottom, thus the upper left pixel is (0,0) and the lower right is (639, 
199). 

There are sixteen colors available for the text and graphics foreground 
color, (only one foreground color can be displayed at any one time). 
The choice of colors is the same as that for screen 0 (Text Mode). On 
monochrome systems the colors are shown as shades of gray. The 
background color is always black. 


SUPER RESOLUTION MODE (SCREEN 3) 

In this mode, there are 640 pixels on the horizontal axis and 400 pix¬ 
els on the vertical axis. These are numbered from left to right and top 
to bottom, thus the upper left corner pixel is (0,0) and the lower right 
corner pixel is (639, 399). 
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There are sixteen colors available for the text and graphics foreground 
color, (only one foreground color can be displayed at any one time). 
The choice of colors is the same as that for screen 0 (Text Mode). On 
monochrome systems the colors are shown as shades of gray. The 
background color is always black. 


WINDOWS AND VIEWPORTS 

In the GW-BASIC graphics environment it is possible to define the 
following types of window: 

• Window 

• Viewport 

A window is a rectangular area with arbitrary dimensions (not limited 
by the physical units of the screen) in which you can draw lines, graphs 
or objects; it is defined using the WINDOW statement. 

A viewport is a rectangular section of the screen, onto which the 
associated window is projected, as shown in Figure 5-2. 



Fig. 5-2 Window and Viewport 


























The command RUN and the statements VIEW and SCREEN, without 
parameters, define the whole screen as a viewport. The VIEW state¬ 
ment, with two pairs of coordinates, defines a subset of the screen 
as a viewport; the first pair specify the top-lefthand corner of the 
viewport, and the second pair specify the bottom-right hand corner. 

You can define more than one viewport. Each time a VIEW statement 
is executed, a viewport is defined; this is the “current” viewport. Thus, 
to change the current viewport, you have to execute another VIEW 
statement. Only points within the current viewport will be drawn; if 
points are specified in a graphics statement, that are outside the cur¬ 
rent viewport, they will not be shown (this is called “clipping ). 


TRANSFORMATION USING WINDOW AND VIEW 

Varying the area of a window or a viewport changes the relationship 
between them. Utilizing this feature, you can produce different images 
from the same design: making it appear smaller or larger (called 
“zooming”); “clipping” a part of the design; or enlarging a detail (a 
combination of zooming and clipping). 

Whilst varying the area of a window, but maintaining the ratio of the 
sides, the image produced will not change; if however, the ratio is 
altered, the image produced will be distorted. 

By defining more than one viewport, which partially overlap in a par¬ 
ticular way, you can compose a picture on the video made up of parts 
of other designs (i.e. from different windows). 

Another possibility is that of defining different viewports associated with 
the same window, using only one WINDOW statement and various 
VIEW statements, all with the SCREEN option specified. This option 
dictates that the points within the window are projected onto the whole 
screen, however, only those points within the current viewport are plot¬ 
ted. In this way you can view various parts of the design. 
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Some examples of these possibilities are given for the WINDOW state¬ 
ment in Chapter 8. 


COORDINATES 

Each point in a design is specified using coordinates, these are inter¬ 
preted in the GW-BASIC environment as: 

• screen coordinates 

• world coordinates 

Screen coordinates are positive integer numbers; the origin of the axes 
is situated in the top-lefthand corner of the screen; the x-axis increases 
towards the right and the y-axis increases towards the bottom. 

World coordinates are signed real numbers; the user defines the posi¬ 
tion of the origin and the direction in which the y-axis increases. 

The WINDOW statement allows you to draw a figure in an area which 
is not restricted by the bounds of the screen, using a user-defined carte¬ 
sian coordinate system. 

After the execution of a WINDOW statement, the coordinates of all 
points given in graphics statements are interpreted by GW-BASIC as 
world coordinates; if a WINDOW statement is not executed the coor- 
dinates of all specified points are interpreted as screen coordinates. 
The DRAW statement is an exception, in that you can only specify 
screen coordinates and you draw directly in the viewport. 

World coordinates are automatically converted by GW-BASIC into 
screen coordinates for subsequent display within the current viewport. 

If the WINDOW statement is executed with no parameters specified, 
the world coorinates will have a one-to-one correspondence with the 
screen coordinates. 

Independenty of the definition of world or screen coordinates, the coor¬ 
dinates of a point can be: 

• absolute coordinates (the STEP option is not specified in the graphics 
statement) 

• relative coordinates (the STEP option is included in the graphics 
statement). 











Absolute coordinates specify the position of a point with respect to the 
origin of the coordinate system. 

Relative coordinates specify the position of a point with respect to the 
coordinates of the last referenced point. 

The following example illustrates the use of both types of coordinates: 

10 SCREEN 1 ’Medium Resolution 
20 PSET (100, 50) 

30 PSET STEP (10, -5) 

Two pixels are drawn; the first at coordinates (100, 50) and the se¬ 
cond at coordinates (110,45). 


ANIMATION TECHNIQUES 

Using the GET statement you can store the graphics image contain¬ 
ed within a specified rectangle on the screen into a numeric array. Us¬ 
ing the PUT statement you can transfer the image back to the screen 
in the same position or in another position. 

Also, using the PUT statement, you can perform logical operations bet¬ 
ween the colors of the pixels composing the stored image and the col¬ 
ors of the pixels on the screen. 

In order to erase an image from the screen, you only have to put the 
image back in the same position, using the PUT statement, with the 
XOR option specified. This is the way in which you animate objects. 

In order to make an object appear to be moving, follow these steps. 

1. Use the PUT statement to transfer the image (previously stored us¬ 
ing the GET statement) onto the screen. 

2. Calculate the new position of the rectangle that contains the image. 

3. Transfer the image into the same position on the screen, using the 
PUT statement, with the XOR option specified (in order to erase 
the image without modifing the background colors). 

4. Go back to step 1 specifying, in the PUT statement, the new posi¬ 
tion of the rectangle that contains the image. 
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In order to move more than one object, you must repeat the procedure 
for each object. 













6. ADVANCED FEATURES 






ABOUT THIS CHAPTER 

This chapter is provided for users who want to call machine language 
subroutines from GW-BASIC, or use event trapping, or Child pro¬ 
cesses. In particular, it covers: 

• Allocation of memory for machine language subroutines 

• Loading machine language subroutines into memory 

• Calling the subroutine from GW-BASIC and passing parameters to it 

• Event Trapping 

• Child Processes 

This chapter is intended for experienced programmers. 
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MACHINE LANGUAGE SUBROUTINES 

You may call machine language subroutines from your GW-BASIC pro¬ 
gram with the USR function or the CALL or CALLS statements. 

The USR function allows you to call a machine language subroutine 
to return a value in the same way you call GW-BASIC intrinsic func¬ 
tions. However, we recommend that you use the CALL or CALLS state¬ 
ment for calling machine language programs from GW-BASIC. These 
statements can pass multiple arguments. In addition, the CALL state¬ 
ment is compatible with more versions of BASIC than is the USR 
function. 


MEMORY ALLOCATION 

Before loading a machine language subroutine into memory you must 
set aside enough memory space to contain it. There are two ways of 
doing this. 

Using the first method you allocate space for the machine language 
subroutines in the GW-BASIC Data Segment (DS), using the CLEAR 
statement or the /M: option of the GWBASIC command. Only the higher 
addresses of the GW-BASIC Data Segment can be used to hold 
machine language subroutines. 

If more stack space is needed when a machine language subroutine 
is called, you can save the GW-BASIC stack and set up a new stack 
for the machine language subroutine. The GW-BASIC stack must be 
restored, however, before you return from the subroutine. 

Using the second method you allocate space for machine language 
subroutines outside of the GW-BASIC Data Segment, using the DEF 
SEG statement giving the start address of a suitable segment. This 
address must be greater than the address of the end of the Data Seg¬ 
ment (64K plus the start address of the Data Segment). 

Which of the two methods you choose is essentially dependent on how 
much memory is available. 








LOADING SUBROUTINES INTO MEMORY 

A machine language subroutine can be loaded into memory in several 
ways, the most simple being to use the BLOAD command . Also, you 
could SHELL a program that exits, but stays resident. As a third choice, 
you could execute a program that exits but stays resident, and then 
run GW-BASIC. 

The following guidelines must be observed if you choose to BLOAD, 
or read and poke, an EXE file into memory: 

1. Make sure the subroutines do not contain any long references, 
address offsets that exceed 64K or that take the user out of the 
code segment. These long references require handling by the EXE 
loader. 

2. Skip over the first 512 bytes of the linker’s output file (EXE), then 
read in the rest of the file. 

The following two sections illustrate two standard ways of loading 
machine language subroutines. 

USING THE POKE STATEMENT 

Machine language subroutines can be POKEd into memory as follows: 
after assembling the subroutine, you should create DATA statements 
containing the value in hexadecimal of each byte of code (represented 
as &Hxx). The subroutine is then POKEd into the specified area of 
memory, byte by byte, in a loop. 

The subroutine may then be called using the USR function or the CALL 
statement. If you use the USR function, then the subroutine entry ad¬ 
dress must be defined with a DEF USR statement. This defines the 
USR function call offset into the current segment. If you use the CALL 
statement, then the subroutine entry address is the value of the numeric 
variable entered just after CALL. This variable must contain the offset 
into the current segment. In both cases, the segment is defined by 
the DEF SEG statement. 
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USING THE BLOAD COMMAND 

A machine language subroutine can be BLOADed into memorv as 
follows: 7 


1 ' . Fir an EXE file of the subroutine using the linker, then 

load GW-BASIC under DEBUG by entering: 


DEBUG GWBASIC.EXE 


2. To determine the location of GW-BASIC in memory, display and 
record the values contained in registers CS, IP, SS, SP, DS, and 
ES, using the R command (for use in step 5). 

3. Load the .EXE file into high memory using DEBUG, overlayinq 
the transient section of COMMAND.COM. 


4. To determine the subroutine memory location, display the registers 
using the R command. The CS and IP register values should be 
recorded for use in steps 6 and 7. 

5. Reset the register values to their original values as recorded in 
step 2 using the R command. Breakpoints may optionally be in¬ 
cluded in the subroutine using the G command which branches 
to the GW-BASIC entry point. 

6. Load your application program. Modify the DEF SEG and either 
the DEF USR statement or the CALL variable to correspond with 
the subroutine memory location as defined in step 4 (i.e., the CS 
register value for DEF SEG and the IP register value for the DEF 
USR or CALL variable). 

7. The subroutine memory area should be BSAVEd in GW-BASIC 
direct mode, using both the CS and IP register values from step 
4, and the assembler listing or LINK map code length. 

8. Ensure that your application program contains a DEF SEG with 
the appropriate CS register value, followed by a BLOAD statement. 

BLOAD can place a subroutine in an alternate location if the 
subroutine is self-relocatable. Possible alternatives include an 
unused screen or file buffer, or a string variable area. (Refer to 
the BLOAD command and VARPTR Function.) In this case 
remember also to modify the associated DEF SEG statement ’ 







9. Finally, the updated application program should be saved onto 
disk. 

Note 

If GW-BASIC is run under DEBUG, DEBUG is loaded first, as a precau¬ 
tion against being overwritten. Any breakpoints, or the SYSTEM com¬ 
mand, returns control to DEBUG. 


CALLING THE SUBROUTINE FROM GW-BASIC 


CALL STATEMENT 

The CALL statement is the recommended way of calling machine 
language programs with GW-BASIC. It is preferable to the USR func¬ 
tion unless you are running programs that already contain USR func¬ 
tions (for reasons of compatibility). 

The syntax of the CALL statement is: 


CALL numvar [ ( variable [ , variable] ... ) ] 


Where 

numvar contains the offset into the current segment that is the star¬ 
ting point in memory of the subroutine being called 

variable is the variable that is passed to the subroutine as an 
argument 

The current segment is either the default (the GW-BASIC Data Seg¬ 
ment) or that which has been specified in the most recently executed 
DEF SEG statement. 
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Invoking the CALL statement causes the following to occur: 

1. For each variable specified in the statement, the two-byte offset 
of the variable’s location within the GW-BASIC Data Segment is 
pushed onto the stack. 

2. The return address specified in the code segment (CS), and off¬ 
set (IP) are pushed onto the stack. 

3. Control is transferred to the machine language routine using the 
segment address, which is given in the last executed DEF SEG 
statement and the offset given in numvar. 

The following diagrams illustrate the state of the stack at the time the 

CALL statement is executed, and during execution of the called 

subroutine, respectively. 


high 

addresses 
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a 

c 
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c 
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t 
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r 


low 

addresses 



SP + 4 + (2*n) 

Each argument is a 2-byte 
pointer into memory 

SP + 6 
SP + 4 
SP + 2 

SP^—stack pointer 
(SP register 
contents) 


Fig. 6-1 Stack Layout when CALL Statement is Activated 


After the CALL statement has been activated, the subroutine has con¬ 
trol. Arguments may be referenced by moving the stack pointer (SP) 
to the base pointer (BP) and adding a positive offset to BP. 
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This space may 
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procedure - 
execution 


> 


Absent if any argument 
is referenced within a 
nested procedure 


Absent in local procedure 

•Stack pointer 
(SP register 
contents) 


Stack pointer may change 
during procedure execution 


Fig. 6-2 Stack Layout During Execution of a CALL Statement 

Observe the following rules when coding a subroutine: 

1. The called routine must preserve segment registers DS, ES, SS, 
and BP. If interrupts are disabled in the routine, they must be 
enabled before exiting. The stack must be cleaned up on exit. 

2. The called subroutine must know the number and length of the 

arguments passed. The following routine shows an easy way to 
reference arguments: 


push BP 

mov BP,SP 

add BP, (2*number of arguments)+ 4 
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Then: 

argument 0 is at BP 
argument 1 is at BP-2 
argument n is at BP-2*n 

(number of arguments = n + 1 ) 

3. Variables may be allocated either in the Code Segment or on the 
stack. Be careful not to modify the return segment and offset stored 
on the stack. 

4. The called subroutine must clean up the stack. A preferred way 
to do this is to return to the main program using a RET n state¬ 
ment (where n is two times the number of arguments in the 
argument list) to adjust the stack to the start of the callinq se¬ 
quence. 

5. Values are returned to GW-BASIC by including in the argument 
list the name of the variable that will receive the result. 

6. If the argument is a string, the argument’s offset points to 3 bytes 
which, as a unit, are called the ’’string descriptor”. Byte 0 of the 
string descriptor contains the length of the string (0 to 255). Bytes 
1 and 2, respectively, are the lower and upper 8 bits of the string 
starting address in string space. 

Note 

If the argument is a string literal, the string descriptor will point 
to program text. Be careful not to alter or destroy your program 
this way. To avoid unpredictable results, you must add +”” to 
the string literal in the program. For example, use: 

20 A$ = ’’BASIC” + ”” 

This will force the string literal to be copied into string space. Then 
the string may be modified without affecting the program. 

7. The contents of a string may be altered by user routines, but the 
descriptor must not be changed. Do not write past the end-of- 
string. GW-BASIC cannot correctly manipulate strings if their 
lengths are modified by external routines. 







8. Data areas needed by the runtirne must be allocated either in the 
CODE segment of the user routine or on the stack. It is not possi¬ 
ble to declare a separate data area in the user machine language 
routine. 


Example 


100 DEF SEG = &H8000 
110 VAR = &H7FA 


120 CALL VAR (A,B$,C) 


Line 100 sets the segment to 80000 Hex. The value of variable VAR 
is added into the address as the low word after the DEF SEG value 
is left shifted 4 bits, i.e. multiplied by 16 (this is a function of the 
microprocessor, not of GW-BASIC). Here VAR is set to &H7FA, so that 
the call to VAR will execute the subroutine at location 80000:7FA Hex 
(absolute address 8007FA Hex). 


The following sequence in 8086 assembly language demonstrates ac¬ 
cess to the arguments passed. The returned result is stored in the 


variable C. 


PUSH 

BP 

MOV 

BP,SP 

ADD 

BP,(4 + 2*3) 

MOV 

BX,[BP-2] 

MOV 

CL,[BX] 

MOV 

DX,1[BX] 


MOV 

SI,[BP] 

MOV 

DI[BP-4] 

MOVS 

WORD 

POP 

BP 

RET 

6 


;Set up pointer to arguments 


Get address of B$ descriptor. 
Get length of B$ in CL. 

Get addr of B$ text in DX. 


Get address of ’A’ in SI. 
Get pointer to ’C’ in Dl. 
Store variable ’A’ in ’C’. 
Restore pointer. 

Restore stack, return. 
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Note 

The called subroutine must know the variable type for the numeric 
arguments. In the previous example, the instruction: 

MOVS WORD 

will copy only two bytes. This is fine if variables A and C are integer. 
You would have to copy four bytes if the variables were single preci¬ 
sion format and copy 8 bytes if they were double precision. 


CALLS STATEMENT 

The CALLS statement should be used to access subroutines that were 
written using MS-FORTRAN calling conventions. CALLS works just 
like CALL, but the arguments are passed as segmented addresses 
rather than as unsegmented addresses. 

Because MS-FORTRAN routines need to know the segment value for 
each argument passed, the segment is pushed and then the offset 
is also pushed. For each argument, four bytes are pushed rather than 
2, as in the CALL statement. Therefore, if your assembler routine is 
entered using the CALLS statement, n in the RET statement is four 
times the number of arguments. 


USR FUNCTION 

Although using the CALL statement is the recommended way of call¬ 
ing machine language routines, the USR function is also available for 
this purpose. This ensures compatibility with programs that contain 
USR functions. 








The format of the USR function is: 


USR [n] ( argument ) 


Where 

n is a digit from 0 to 9. It specifies which USR routine 

is being called. If n is omitted, USRO is assumed. 

argument is any numeric or string expression, passed as an 

argument to the subroutine. The argument must 
always be specified, even if it isn’t required by the 
subroutine (i.e. a dummy argument). 

For each USR function, a corresponding DEF USR statement must 
be executed to define the offset with respect to the starting address 
of the current segment. This offset and the currently active DEF SEG 
address determine the starting address of the subroutine. 

When the USR function call is made, register AL contains a value that 
specifies the type of argument. The value in AL may be one of the 
following: 

2 two-byte integer (two’s complement) 

3 string 

4 single precision floating-point number 

8 double precision floating-point number 


If the argument is a number, the BX register points to the Floating- 
Point Accumulator (FAC) where the argument is stored. FAC is an 
8-byte area in the GW-BASIC Data Segment. 

If the argument is an integer: 

FAC-2 contains the upper 8 bits of the argument 
FAC-3 contains the lower 8 bits of the argument 
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If the argument is a single precision floating-point number (24-bit 
mantissa): v 

FAC-2 contains the middle 8 bits of mantissa. 

FAC-3 contains the lowest 8 bits of mantissa. 

If the argument is a double precision floating-point number (56-bit 
mantissa): 

FAC-7 through FAC-4 contain four more bytes of mantissa 
(FAC-7 contains the lowest 8 bits). 

If the argument is a string, the DX register points to 3 bytes which, 
as a unit, are called the ’’string descriptor”. Byte 0 of the string descrip¬ 
tor contains the length of the string (0 to 255 characters). Bytes 1 and 
2, respectively, are the lower and upper 8 bits of the string starting 
address in the GW-BASIC data segment. If the argument is a string 
literal in the program, the string descriptor will point to program text. 
Be careful not to alter or destroy the program this way. 

Usually, the value returned by a USR function is the same type (in¬ 
teger, string, single precision, or double precision) as the arqument 
that was passed to it. 

GW-BASIC has extended the USR function interface to allow calls to 
MAKINT and FRCINT. This allows access to these routines without 
giving their absolute addresses. The address ES:BP is used as an in¬ 
direct far pointer to the routines FRCINT and MAKINT. 

To call FRCINT using a USR routine use CALL DWORD ES:[BP1. 
To call MAKINT using a USR routine use CALL DWORD ES:[BP + 4], 


Example 

110 DEF USR0 = &H8000 ’Assumes user gave /M 32767 

120 X = 5 

130 Y = USRO(X) 

140 PRINT Y 

The type (numeric or string) of the variable receiving the function call 
must be consistent with that of the argument passed. 







EVENT TRAPPING 

Event trapping allows the transfer of control to a program line when 
a certain event occurs. Control is transferred as if a GOSUB statement 
had been executed to the trap routine starting at the specified line 
number. The trap routine, after servicing the event, executes a 
RETURN statement that causes the program to resume execution at 
the place where it was when the event trap occurred. 

The events that can be trapped are receipt of characters from a com¬ 
munication port (ON COM (n) GOSUB), detection of certain keystrokes 
(ON KEY (n) GOSUB), time passage (°NJJJVIER (n) GC^UB), or emp¬ 
tying of the background music queue (ON PLAY (n) GOSUB). 

Event trapping is controlled by the following statements: 

Syntax 1 (to turn on trapping) 


(COM( n ) | KEY( n ) | TIMER | PLAY } ON 


Syntax 2 (to turn off trapping) 


( COM( n ) | KEY( n ) | TIMER | PLAY ] OFF 


Syntax 3 (to temporarily turn off trapping) 


{ COM( n ) | KEY( n) \ TIMER | PLAY ) STOP 
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Remarks 

COM(n) where n is the number of the communications port. 

Typically, the COM trap routine will read an entire message 
from the specified port before returning. We do not recom¬ 
mend using the COM trap for single character messages 
because at high baud rates the overhead of trapping and 
reading for each character may allow the interrupt buffer for 
COM to overflow. 

KEY(n) where n is a trappable key number. Trappable keys are 
numbered 1 through 20. 

Note that KEY(n) ON is not the same statement as KEY ON. 
KEY(n) ON sets an event trap for the specified key. KEY ON 
displays the values of all the function keys on the twenty-fifth 
line of the screen. 

When GW-BASIC is in direct mode function keys maintain 
their standard meanings. 

When a key is trapped, that occurrence of the key is 
destroyed. Therefore, you cannot subsequently use the IN¬ 
PUT or INKEY$ statements to find out which key caused the 
trap. So if you wish to assign different functions to particular 
keys, you must set up a different subroutine for each key, 
rather than assigning the various functions within a single 
subroutine. 

TIMER The ON TIMER(n) GOSUB statement (where n is a 

numeric expression representing a number of seconds since 
the previous midnight) can be used to perform background 
tasks at defined intervals. 

PLAY The ON PLAY(n) GOSUB statement (where n is a 

number of notes left in the music buffer) is used to retrieve 
more notes from the background music queue, to permit con¬ 
tinuous background music during program execution. 








THE ON GOSUB STATEMENT 

The ON GOSUB statement sets up a line number for the specified 
event trap. The format is: 


ON jCOM( n ) | KEY( n ) | TIMER( n ) | PLAY( n ) ] GOSUB linenum 


A linenum of zero disables trapping for that event. 

When an event is ON and if a non-zero line number has been specified 
in the ON GOSUB statement, every time GW-BASIC starts a new state¬ 
ment it will check to see if the specified event has occurred (e.g., a 
COM character has come in). When an event is OFF, no trapping takes 
place, and the event is not remembered even if it takes place. 

When an event is STOPped, no trapping takes place, but the occur¬ 
rence of that event is remembered so that an immediate trap will take 
place when the associated event ON statement is executed. 

When a trap is made for a particular event, the trap automatically 
causes a STOP on that event, so recursive traps can never occur. A 
return from the trap routine automatically executes an ON statement 
unless an explicit OFF has been performed inside the trap routine. 

Note that once an error trap takes place, all trapping is automatically 
disabled. In addition, event trapping will never occur when GW-BASIC 
is not executing a program. 

THE RETURN STATEMENT 

When an event trap is in effect, a GOSUB statement will be executed 
as soon as the specified event occurs. For example, the statement: 

ON KEY(IO) GOSUB 1000 

specifies that the program go to line 1000 as soon as Function Key 
Fio is pressed. If a simple RETURN statement is executed at the end 
of this subroutine, program control will return to the statement follow¬ 
ing the one where the trap occurred. When the RETURN statement 
is executed, its corresponding GOSUB return address is cancelled from 
the stack. 


6-14 


GW-BASIC INTERPRETER USER GUIDE 










ADVANCED FEATURES 


GW-BASIC includes the RETURN linenum enhancement which 
lets processing resume at a definable line. Normally, the program 
returns to the statement immediately following the GOSUB statement 
when the RETURN statement is encountered. However, RETURN 
linenum enables you to specify another line. If not used with care 
however, this capability may cause problems. Assume, for example’ 
that your program contains: ’ 

10 ON KEY(10) GOSUB 1000 
20 FOR I = 1 TO 10 
30 PRINT I 
40 NEXT I 

50 REM NEXT PROGRAM LINE 
200 REM PROGRAM RESUMES HERE 
1000 ’FIRST LINE OF SUBROUTINE 


1050 RETURN 200 

If the Function Key F10 is pressed while the FOR/NEXT loop is ex¬ 
ecuting, the subroutine will be performed, but program control will 
return to line 200 instead of completing the FOR/NEXT loop. The 
original GOSUB entry will be cancelled by the RETURN statement 
and any other GOSUB, WHILE, or FOR, that was active at the time 
of the trap will remain active. The current FOR context will also re¬ 
main active, and a ’’FOR without NEXT” error may result. 


GW-BASIC AND CHILD PROCESSES 

Through the use of the SHELL command, GW-BASIC is able to use 
one of the most powerful features of MS-DOS: the ability to create child 
processes. SHELL enables you to run part of a GW-BASIC program 
temporarily exit to MS-DOS to perform a specified function, and return 
to the GW-BASIC program at the statement after the SHELL command 
to proceed with the rest of the program. 









GW-BASIC will produce a child program when it uses the SHELL com¬ 
mand. It is not possible for GW-BASIC to totally protect itself from its 
children. When a SHELL command is executed, many things may be 
going on. For example, files may be OPEN and devices may be in use. 

The following guidelines will help to prevent child processes from har¬ 
ming the GW-BASIC environment. 


HARDWARE 

In general, it is recommended that the state of all hardware be preserv¬ 
ed during a SHELL command. The implementation interface provides 
a way for performing this task. However, it may be necessary to re¬ 
quest that you refrain from using certain devices within child processes 
which are executed using the GW-BASIC SHELL command. Specific 
areas of concern are as follows: 

1. Screen Device - Child processes might modify screen mode 
parameters. However, useful information may be displayed by a 
child process. 

2. Interrupt Vectors - Save and restore interrupt vectors the child in¬ 
tends to use. 

3. Other hardware - Many devices are placed in a specific state by 
GW-BASIC. Such devices may include an Interrupt Controller, 
Counter Timers, DMA Controller, I/O Latch, and Uarts. These 
devices may be utilized by the child process without the user be¬ 
ing aware of any limitations. 


THE FILE SYSTEM 

A Child that alters any file open in the GW-BASIC parent may have 
disastrous results. 

If it is necessary to update such files, they should be CLOSEd inthe 
parent before doing a SHELL, then re-OPENed upon return to the GW- 
BASIC parent. (See ’’Re-direction of Standard Input and Standard Out¬ 
put” in Chapter 8, under the GWBASIC command). 
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MEMORY MANAGEMENT 

1. Before GW-BASIC SHELLS to COMMAND it will try to free any 
memory it is not using with one exception: when GW-BASIC is 
run with the /M: switch. In this case, GW-BASIC must assume that 
you intended to load a routine in the top of GW-BASIC’s Memory 
Block. This prevents GW-BASIC from ’’compressing the 
workspace” before doing the SHELL. For this reason SHELL may 
fail on an ’’Out of memory” error when using the /M: switch. 

The preferred method is to load machine language subroutines 
before GW-BASIC is run. This can be accomplished by placing 
Pocket Code” at the end of machine language subroutines that 
allows them to exit to MS-DOS and stay resident. For example: 

CSEG SEGMENT CODE 


;Machine language subroutine 


RET ;Last instruction 

START:: 

INT 27H Terminate, stay resident 

CSEG ENDS 

END START 

be sure to ’’load” these subroutines before GW-BASIC by runn¬ 
ing them. The AUTOEXEC.BAT file is very useful for this. 

2. A Child should never "terminate and stay resident”. Doing so may 
not leave GW-BASIC enough room to expand it’s workspace to 
the original size. If GW-BASIC cannot restore the workspace, all 
files are closed, the error message ’’SHELL can’t continue” is 
printed, and GW-BASIC exits to MS-DOS. 
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ABOUT THIS CHAPTER 

This chapter describes how GW-BASIC may be used to support RS232 
asynchronous communications with other computers and peripherals. 

This chapter is intended for experienced programmers interested in 
setting up and using asynchronous communications. 
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OPENING COMMUNICATIONS FILES 


The OPEN COMmunications statement allocates a buffer for input and 
output in a similar manner as the OPEN statement for disk files. Refer 
to Chapter 8 for a full description. 


COMMUNICATION I/O 


Since the communication port is opened as a file, all Input/Output 
statements that are valid for disk files are valid for COM. 

COM sequential input statements are the same as those for disk files 
They are: INPUT #, LINE INPUT #, and the INPUT$ function. 

COM sequential output statements are the same as those for disk, and 
are: PRINT #, PRINT # USING, and WRITE #. 


Refer to the INPUT and PRINT statements in Chapter 8 for details of 
coding syntax and usage. 


The GET and PUT statements are only slightly different for COM files 
See the ’’GET (COM Files)” and ’’PUT (COM Files)” statements 
described in Chapter 8. 


COMMUNICATION I/O FUNCTIONS 

The most difficult aspect of asynchronous communication is being able 
to process characters as fast as they are received. At rates above 2400 
bps., it may be necessary to suspend character transmission from the 
host computer long enough to ’’catch up”. This can be done by sen¬ 
ding XOFF (CHR$(19)) to the host and XON (CHR$(17)) when ready 
to resume. 


GW-BASIC provides three functions which help in determining when 
an ’’over-run” condition is imminent. These are: 


LOC(f) 


Returns the number of characters in the input buffer waiting 
to be read. The input buffer can hold more than 255 
characters (determined by the 1C: switch). If there are more 
than 255 characters in the buffer, LOC(f) returns 255. Since 
a string is limited to 255 characters, this practical limit 
means that you do not have to test for string size before 
reading data into it. If fewer than 255 characters remain in 
the buffer, LOC(f) returns the actual count. 





LOF(ft Returns the amount of free space in the input buffer. That 
is, s/ze-LOC(/)> where size is the $ize of the communica¬ 
tions buffer as set by the 1C: option. LOF may be used to 
detect when the input buffer is reaching its maximum 
capacity. 

EOF (f) If true (-1), indicates that the input buffer is empty. Returns 

false (0) if any characters are waiting to be read. 


Possible Errors 

’’Communication Buffer Overflow” 

If a read is attempted after the input buffer is full, (i.e. LOF(/) returns 0). 
’’Device I/O Error” 

If any of the following line conditions are detected on reception: Over¬ 
run Error (OE), Framing Error (FE), or Break Interrupt (Bl). The error 
is reset by subsequent inputs but the character causing the error is lost. 

’’Device Fault” 

If Data Set Ready (DSR) is lost during I/O. 


THE INPUTS FUNCTION FOR COMMUNICATION FILES 

The INPUTS function is preferable to the INPUT # and LINE INPUT # 
statements when reading COM files, since all ASCII characters may 
be significant in communications. INPUT # is least desirable because 
input stops when a comma (,) or CR is received and LINE INPUT # 
terminates when a CR is received. 

INPUTS allows all characters read to be assigned to a string. 
Remember from the coding rules that INPUTS (n,f) will return n 
characters from the #/file. The following statements are therefore the 
most efficient for reading a COM file: 

10 WHILE NOT EOF(1) 

20 A$ = INPUTS (LOC(1),#1) 

30 ... 

40 Process data returned in A$ 

50 ... 

60 WEND 
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The above statements return the characters in the buffer into A$ and 
process them, provided there are characters in the buffer. If there are 
more than 255 characters, only 255 will be returned at a time to pre¬ 
vent ’’String Overflow”. If this is the case, EOF(1) is false and input 
continues until the input buffer is empty. The sequence of events is 
therefore simple, concise, and fast. 


AN EXERCISE IN COMMUNICATION I/O 

The following program enables your Personal Computer to be used 
as a conventional terminal. Besides Full Duplex communication with 
another computer, the TTY program allows received data to be ’’Down¬ 
loaded” to a file. Conversely, a disk file may be ’’Up-loaded” (transmit¬ 
ted) to another machine. 


In addition to demonstrating the elements of Asynchronous com¬ 
munication, this program should be useful in transferring GW-BASIC 
programs and Data to and from your system. 



10 REM 

20 REM * * * RS232 test program * * * 

30 REM 

40 SCREEN 0,0 
50 KEY OFF:CLS:CLOSE 
60 DEFINT A-Z 
62 LOCATE 25,1 
64 PRINT STRING$(60,“ ”) 

70 FALSE = 0:TRUE = NOT FALSE 
80 MENU = 5 

90 XOFF$ = CHR$(19):XON$ = CHR$(17) 

92 LOCATE 25,1 PRINT “TTY Async Program” 
94 LOCATE 1,1:LINE INPUT “Baud?”; SPEEDS 
100 ON COM(1) GOSUB 730 
110 COMFIL$ = “COM1:” +SPEEDS+ “ E 7” 

120 OPEN COMFILS AS 1 


Fig. 7-1 The TTY Program 
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* * * 


talk mode *** 


130 REM 
140 REM 
150 REM 
160 CLS 

170 LOCATE 25,1 : PRINT“RS232 test program running in TALK 
MODE”; 

180 PAUSE = FALSE 
190 LOCATE 1,1 

200 A$ = INKEY$: IF A$ = ”” THEN 220 

210 IF ASC(A$) = MENU THEN 290 ELSE PRINT#1,A$; 

220 IF EOF(1) THEN 200 

230 IF LOC(1)>50 THEN PAUSE = TRUE: PRINT #1,XOFF$; 
240 A$ = INPUT$(LOC(1),1) 

250 PRINT A$;:IF LOC(1)>0 THEN 230 

260 IF PAUSE THEN PAUSE = FALSE:PRINT # 1 ,XON$; 

270 GOTO 200 
280 REM 

290 REM *** command mode *** 

300 REM 
310 CLS 

320 LOCATE 25,1 PRINT “RS232 test program running in 
COMMAND MODE”; 

330 LOCATE 1,1 

340 INPUT“FILE”;DSKFIL$ 

350 LOCATE 1,1 PRINT STRINGS (80,“ ”):LOCATE 1,1 
360 INPUT‘‘(T)ransmit or (R)eceive”;TXRX$ 

370 IF TXRX$ = “T” THEN OPEN DSKFIL$ FOR INPUT AS 
3:GOTO 580 

380 IF TXRX$ = “R” THEN 410 
390 GOTO 350 
400 REM 

410 REM *** file receive mode *** 

420 REM 

430 LOCATE 25,32 : PRINT “FILE RECEIVE MODE”; 

440 OPEN DSKFILS FOR OUTPUT AS 3 
450 IF EOF(1) THEN GOSUB 520 

460 IF LOC(1)>50 THEN PAUSE = TRUEPRINT # 1 ,XOFF$; 
470 A$ = INPUT$(LOC(1),1) 

480 PRINT#3,A$; 

490 IF LOC(1)>0 THEN 460 


Fig 7-1 The TTY Program (cont.) 
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500 IF PAUSE THEN PAUSE = FALSE:PRINT# 1 ,XON$- 

510 GOTO 450 

520 FOR I = 1 TO 5000 

530 IF NOT EOF(1) THEN RETURN 

540 NEXT I 

550 CLOSE# 3 

560 RETURN 140 

570 REM 

580 REM *** file transmit mode *** 

590 REM 

600 LOCATE 25,32 : PRINT“FILE TRANSMIT MODE”- 

610 COM(1) ON 

620 XFLAG = 1 

630 WHILE NOT EOF(3) 

640 A$ = INPUT$(1,3) 

650 WHILE XFLAG =0 :WEND 
660 PRINT# 1,(A$); 

670 WEND 

680 COM(1) OFF 

690 PRINT#1,CHR$(26); 

700 CLOSE 3 
710 GOTO 140 
720 REM 

730 REM *** XON/XOFF receiving routine *** 

740 REM 

750 IF EOF(1) THEN RETURN 
760 B$ = INPUT$(LOC(1),1) 

770 IF LEN(B$) = 2 THEN 790 
780 IF B$ = XOFF$ THEN 810 
790 XFLAG = 1 
800 RETURN 
810 XFLAG = 0 
820 RETURN 


Fig. 7-1 The TTY Program (cont.) 









Notes on the TTY Programming Example 


Line No. 

Comments 

10-90 

Define the screen attributes and initialize program 
variables. 

94 

Permits the user to enter the communication speed 
(bps), from the keyboard. 

100 

Specifies the line number of the first statement of the 
COM trap routine associated with channel number 1. 

110-120 

Open and initialize communications channel 1 with the 
speed entered from the keyboard (bps), parity even, 
and 7 data bits. 

170 

Displays a message indicating the operation mode 
(Talk Mode) on the 25th screen line. 

180-260 

Send characters entered from Keyboard to channel 
number 1, and displays characters received from the 
channel. Statement 210 transfers control to statement 
290 (where Command Mode is entered), if the user 
enters CTRL E. 

320 

Displays a message indicating the new mode (Com¬ 
mand Mode) on the 25th screen line. 

340 

Asks the user to enter the name of the file to transmit 
or receive, depending on the character (T or R) entered 
upon execution of statement 360. 

370 

If the user enters T, open the specified file for INPUT 
and branches to statement 580. 

380 

If the user enters R, branches to statement 410 (where 
Receive Mode is entered). 
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410-560 

The program is in Receive Mode, as displayed bv 
statement 430 on the 25th screen line. Statement 440 
opens the specified file for OUTPUT. Statement 450 
checks if characters are pending on the receive buf¬ 
fer. If no characters are pending, control is transfer- 

Sement^e W). 20 ' °' herWiSe '° , °"°"' i " 9 

460 

Checks if the number of characters in the receive buf¬ 
fer is greater than 50. If the number is greater than 

50, it sends an XOFF$ character to the channel to stop 
transmission. K 

470-480 

If the number of characters in the receive buffer is less 
than or equal to 50, characters are read from the 
receive buffer and written to the file. 

490-510 

• 

Check if there are still characters on the receive buf- 
ter. If yes, control is transferred to statement 460. If 
not an XON$ character is sent (if an XOFF$ was sent 
before) and control is transferred to statement 450. 

520-540 

A FOR/NEXT loop is activated to wait until characters 
arrive in the receive buffer. If no character arrives 
within the specified number of iterations, the Receive 

Mode is exited. Control is then transferred to statement 

550 where the file is closed, and then to statement 140 
returning in “TALK MODE”. If characters arrive con¬ 
trol is transferred to statement 460 
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570-710 


730-820 


The program is in Transmit Mode, as displayed by 
statement 600 on the 25th Screen Line (“File Transmit 
Mode”). The file has already been opened for input 
at statement 370. Statement 610 enables COM trap¬ 
ping. Statements 630 to 670 form a WHI LEA/VEND 
loop to read and transmit the file (statement 640 reads 
one character at a time and statement 660 sends it 
to the communications channel). The character 
transmission is suspended if an XOFF$ character is 
received (see statement 650). The character transmis¬ 
sion is resumed if an XON$ character is received 
Statements 680 to 710 disable COM trapping, send 
an EOF character, close the file and return to Talk 

Mode”. 

Form the COM trap routine. Statement 750 checks if 
characters are pending in the receive buffer. If no 
character is pending a RETURN is executed. If two 
characters are pending, the transmission of characters 
is enabled (statement 790) and the routuine is exited 
(RETURN). Two characters in the receive buffer 
means that both an XON$ and an XOFF$ have been 
received. If only one character is pending the transmis¬ 
sion of characters is disabled (if this character is 
XOFF$) or enabled (if this character is XON$). 
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ABOUT THIS CHAPTER 
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COMMANDS, STATEMENTS AND FUNCTIONS 


INTRODUCTION 

This chapter contains information on all the commands, statements 
and functions used in GW-BASIC. An introduction to each constitutes 
the first few pages, followed by a complete alphabetical list. For each 
command, statement or function, this chapter will give the purpose, 
the syntax, the characteristics, one or more examples, and possibly 
remarks. 


Statements and Commands 

It is sometimes difficult to distinguish a GW-BASIC statement from a 
GW-BASIC command, as both may be used in a program or an im¬ 
mediate line; however: 

• GW-BASIC statements are generally used in program lines and 
entered in sequence to form a program. 

• GW-BASIC commands are generally used in immediate lines to 
manipulate programs and for utility purposes, such as listing pro¬ 
grams or clearing the memory. 


Functions 

A function may be thought of as an algorithm returning a single value. 
There are both user functions and built-in functions. It can be called 
simply by stating its name, followed (in parentheses) by one or more 
arguments representing the values that the function parameters are 
to assume. A function may be called both from a program and an im¬ 
mediate line (with the exception of EOF that may only be called from 
a program line). 

A function may be numeric if it returns a numeric value, or a string 
function if it returns a string value. 

All built-in functions are listed in this chapter. For information on how 
to calculate mathematical functions which may be easily derived from 
built-in functions, refer to Appendix B. 








COMMANDS 

The following is a list of all the commands used in GW-BASIC. 

AUTO 

Generates a line number after every carriage return. 

BLOAD 

Loads a memory image file into memory. 


BSAVE 

Saves sections of the main memory on the specified file. 


CHDIR 

Changes the current directory. 


CLEAR 

Clears all numeric variables to zero, all string variables to null, and 
closes all open files. Options set the highest memory location 
available for use by GW-BASIC, and the amount of stack space. 


CONT 

Resumes program execution after a CTRL BREAK has been 
typed or a STOP or END statement has been executed. 


DELETE 

Erases program lines. 
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EDIT 

Lets you change a specified program line. 

FILES 

Displays the names of files residing on the specified directory. 

GWBASIC 

Initializes GW-BASIC and the operating environment (GWBASIC is 
an MS-DOS command, not a GW-BASIC command). 

KILL 

Deletes a disk file. 

LCOPY 

Dumps the screen (text and graphics) to the line printer. 


LIST 

Lists the current program to the screen or a specified file or device. 

LUST 

Lists the current program on the printer. 

LOAD 

Loads a program into memory from a specified drive and, optionally 
runs it. 







MERGE 


Merges the current program with a specified file previously saved 
in ASCII format. 

MKDIR 

Permits the creation of a new directory on a specified disk. 

NAME 

Changes the name of a disk file. 


NEW 


Deletes the current program and clears all variables, allowing you 
to enter a new program. 

RENUM 

Changes the line numbers of the current program. 

RESET 

Closes all open data files on all drives. 

RMDIR 

Removes a directory from a specified disk. 



RUN 



Runs the current program or loads a program from disk and runs it. 
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SAVE 

Saves the current program on disk and gives it a name. 


SHELL 

Loads and executes another program (.EXE, .COM or .BAT). 


SYSTEM 

Closes all open data files and returns control to MS-DOS. 


TRON 

Causes the line number of each statement executed to be listed. 


TROFF 

Stops the line number listing initiated by TRON. 


STATEMENTS 

This part lists all the GW-BASIC statements. They are divided into two 
categories: I/O (Input/Output) Statements and Non-I/O Statements. 


NON-I/O STATEMENTS 
CALL[S] 

Transfers control to a machine language subroutine. The CALLS 
statement is executed in the same way as the CALL statement and 
should be used when accessing routines written with FORTRAN call¬ 
ing conventions. 









CHAIN 


Transfers control and passes variables to another program. 


COM(n) 

COM (n) ON enables, COM (n) OFF disables, and COM (n) STOP 
suspends event trapping of communications activity on the specified 
channel. 


COMMON / 

Defines a common area which is not erased by the CHAINed pro¬ 
gram, and allows you to pass variables from one program to another. 


DATES 


Sets the current date. 


DEF FN 

Defines and names a user-written function. 


DEF SEG 

Assigns the current ’’segment” address. 

DEF USR 

Enables access to a machine language subroutine by specifying the 
starting address. 


DEFINT, DEFSNG, DEFDBL and DEFSTR 


Declare the variable type in accordance with the letter(s) specified. 
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DIM 

Specifies the array name, the number of dimensions and the 
subscript upper bound per dimension. The DIM statement may 
specify one or more arrays. 


END 

Terminates program execution, closes all open data files, and returns 
to command level. 


ENVIRON 

Allows modification of parameters in GW-BASIC’s Environment 
String Table. 


ERASE 

Releases space and variable names previously reserved for arrays. 


ERROR 

Simulates the occurrence of a GW-BASIC error, or generates a user 
defined error. 


FOR/NEXT 

Allow a series of statements to be performed in a loop a given number 
of times. 


GOSUB/RETURN 

GOSUB transfers control to a GW-BASIC subroutine by branching 
to the specified line. RETURN transfers control to the statement 
following the most recent GOSUB (or ON...GOSUB) executed. 





GOTO 


Transfers control to a specified program line. 


IF ... GOTO ... ELSE 

or 

IF ... THEN ... ELSE 

Make a decision regarding program flow based on the result of a 
specified condition. 


KEY 

Sets a function key to automatically type any sequence of characters. 
Other options allow you to enable or disable the function key display 
from the 25th line, or to list the function key values. 


KEY(n) 

KEY(n) ON enables, KEY(n) OFF disables, and KEY(n) STOP 
suspends event trapping of the specified key. 


LET 

Assigns a value to a variable. 


MID$ 

Replaces a part of a string with another string. 


ON COM(n) GOSUB 

Specifies the first line number of a subroutine to be activated as soon 
as characters arrive in the communications buffer. 
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ON ERROR GOTO 

Enables error trapping and specifies the first line number of a 
subroutine to be executed if an error occurs. 

ON ... GOSUB 

Calls one of several specified subroutines, depending on the value 
of a specified expression. 


ON ... GOTO 

Branches to one of several specified line numbers, depending on 
the value of a specified expression. 


ON KEY(n) GOSUB 

Specifies the first line number of a subroutine to be executed when 
a specified function key or cursor control key is pressed. 


ON PLAY(n) GOSUB 

Specifies the first line number of a subroutine to be executed when 
the music buffer contains fewer than n notes. 


ON TIMER(n) GOSUB 

Causes an event trap every n seconds. 


OPTION BASE 

Defines the minimum value for array subscripts. 




PLAY 


Plays music in accordance with a string which specifies the notes 
to be played, and the way in which the notes are to be played. 


PLAY ( ON | OFF | STOPj 

PLAY ON enables, PLAY OFF disables, and PLAY STOP suspends 
play event trapping. 


POKE 

Writes a byte into a memory location. 


RANDOMIZE 


Reseeds the random number generator. 


REM 


Allows explanatory remarks to be inserted in a program. 


RESTORE 

Permits DATA statements to be re-read either from the beginning 
of the internal file or from a specified line. 


RESUME 

Continues program execution after an error trapping routine has 
been performed. 


STOP 


Terminates program execution then returns to command level. 
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SWAP 

Exchanges the values of two variables. 


TIMES 

Sets the current time. 


TIMER 

TIMER ON enables, TIMER OFF disables, and TIMER STOP 
suspends real time event trapping. 


WAIT 

Suspends program execution while monitoring the status of a 
machine input port. 


WHILE/WEND 

Loop through a series of statements as long as a given condition 
remains true. 


I/O STATEMENTS 
BEEP 

Activates the bell. 


CIRCLE 

Draws a circle (or an ellipse) with the specified center and radius 
(Graphics mode only). 




CLOSE 


Terminates I/O to a file or device. 


CLS 

Erases all or part of the screen. 

COLOR (SCREEN 0) 

Sets the text foreground and background. 


COLOR (SCREEN 1) 

Defines the palette background and foreground colors in Medium 
Resolution. In addition, the default graphics foreground and 
background colors, and the text foreground color can be defined. 


COLOR (SCREEN 2 AND 3) 

Defines .the graphics and text foreground. 


DATA 

Creates an ’’internal” file, i.e. a sequence of data belonging to the 
program. Each data item will then be assigned to a program variable 
by a READ statement. 
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DRAW 

Draws an object as specified by the contents of a string expression. 
(Graphics Mode only.) 


FIELD 

Allocates space for variables in a random file buffer. 


GET (COM Files) 

Reads a specified number of bytes into the communications buffer. 


GET (Files) 

Reads a record from a random disk file into a random buffer. 


GET (Graphics) 

Reads points from a screen area. 


INPUT 

Allows input from the keyboard during program execution. 


INPUT# 

Reads data items from a sequential disk file and assigns them to 
program variables. 


IOCTL 

Sends a ’’Control Data” string to a Character Device Driver anytime 
after the Driver has been OPENed. 




LINE 


Draws either a line or a 
Mode only). 


rectangle, or a filled rectangle (Graphics 


LINE INPUT 

Inputs an entire line (up to 254 characters) to a string variable, without 
the use of delimiters. 


LINE INPUT# 

Reads an entire line (up to 254 characters), without delimiters, from 
a sequential disk data file to a string variable. 


LOCATE 


Moves the cursor to the specified position on the active page. 
LOCATE in Text Mode may also turn the cursor on and off and define 
the size of the cursor. 


LOCK 

Restricts access by other processes to all or part of an opened file. 


LPRINT 

Prints data on the printer. 


LPRINT USING 

Prints data to the printer using a specified format. 


LSET/RSET 


Moves data from memory to a random file buffer. 
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OPEN 

Allows I/O to a file or device. 

OPEN COM 

Opens and initializes a communications channel for input/output. 

OUT 

Transmits a byte to an output port. 

PAINT 

Paints an enclosed area on the screen with a specified color 
(Graphics Mode only). 

PRESET 

Draws a point at the specified position on the screen (Graphics Mode 
only). 

PRINT 

Outputs data to the screen. 

PRINT USING 

Outputs data to the screen using a specified format. 

PRINT# 

Writes data sequentially to a disk file. 





PRINT# USING 

Writes data sequentially to a disk file, using a specified format. 


PSET 

Illuminates a pixel at a specified position on the screen (Graphics 
mode only). 

PUT (COM Files) 

Writes a specified number of bytes to a communications file. 


PUT (Files) 

Writes a record from a random buffer to a random disk file. 


PUT (Graphics) 

Transfers the graphics image stored in an array to the screen. 


READ 

Reads values from one or more DATA statements and assigns them 
to variables. 


RESET 

Closes all open data files on all drives. 

SCREEN 

Sets the specifications for the display screen. 
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SOUND 

Produces sound via a speaker. 

UNLOCK 

Releases locks applied to an open file. 

VIEW 

Defines subsets of the screen called ’viewports’, into these, window 
contents will be mapped. (Graphics Mode only.) 

WIDTH 

Sets the line width in characters. 


WINDOW 

Defines the logical dimensions of the current viewport. (Graphics 
Mode only). 

WRITE 

Writes data to the screen. 


WRITE# 

Writes data to a sequential file. 





FUNCTIONS 


This section lists all built-in (or intrinsic) functions used in GW-BASIC. 
They are divided into two categories: numeric and string functions. 
Further classes are defined within each category. 


NUMERIC FUNCTIONS (returning a numeric value) 


Arithmetic 

ABS 

Returns the absolute value of a numeric expression. 


ATN 

Returns the arctangent of the argument. 


CDBL 

Converts a given numeric expression to a double precision number. 


CINT 

Converts any numeric argument to an integer by rounding the frac¬ 
tional portion. 


COS 

Returns the cosine of the argument. 


CSNG 

Converts any numeric argument to a single precision number. 


8-18 


GW-BASIC INTERPRETER USER GUIDE 




COMMANDS, STATEMENTS AND FUNCTIONS 


EXP 

Returns e (base of natural logarithms) to the power of the 
argument. 

FIX 

Returns the truncated integer part of the argument. 

INT 

Returns the largest integer that is equal to, or less than the argument. 

LOG 

Returns the natural logarithm of a positive argument. 

RND 

Returns a random number between 0 and 1. 

SGN 

Returns 1 if the argument is positive, 0 if the argument is zero, and 
-1 if the argument is negative. 

SIN 

Calculates the sine of the argument. 

SQR 

Returns the square root of a positive numeric expression. 




TAN 


Returns the tangent of the argument. 


String-Related 

ASC 

Returns a numeric value that is the ASCII code for the first character 
of a given string. 

{ CVI | CVS | CVD ] 

Convert string values to numeric values. 


INSTR 


Searches for the first occurrence of a given substring in a string, 
and returns the position at which the match is found. 


LEN 

Returns the number of characters in a given string. 

VAL 

Converts the string representation of a number to its numeric value. 


I/O and Miscellaneous 


CSRLIN 

Returns the current line (row) position of the cursor. 
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EOF 

Indicates that the end of a file has been reached. 


ERDEV 

Holds the actual value of a Device error. 

ERR 

Returns the error code. 

ERL 

Returns the number of the line which contains the error. 

FRE 

Returns the number of bytes in memory not being used by 
GW-BASIC. 

INP 

Returns the byte read from a port. 

LOC 

Returns the current position in the file. 

LOF 

Returns the number of bytes allocated to the file. 






LPOS 


Returns the current position of the print head within the printer buffer. 


PEEK 

Returns the byte read from the specified memory location. 


PLAY 

Returns the number of notes currently in the music background 
buffer. 


PMAP 


Maps physical coordinates to world coordinates or world coordinates 
to physical coordinates (Graphics Mode only). 


POINT 

Returns the color of a pixel on the screen or the current graphics 
coordinate (Graphics Mode only). 


POS 

Returns the current cursor column position. 

SCREEN 

Returns the ASCII code (0-255) or the color number for the character 
at the specified screen location. 



TIMER 

Returns a single-precision number indicating the seconds that have 
elapsed since midnight or system reset. 
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USR 

Calls a machine language subroutine. 


VARPTR 

VARPTR ( variable ) returns the address of variable. 
VARPTR ( filenum ) returns the starting address of the disk I/O buf¬ 
fer (for sequential files) or the starting address of the FIELD buffer 
(for random files). 


STRING FUNCTIONS (returning a string value) 


General 

CHR$ 

Returns a one-character string whose ASCII code is the value of the 
argument. 


LEFTS 

Returns a substring extracting a number of characters to the left of 
a given string, as specified by the length parameter. 


MID$ 

Returns a substring from a specified string. 


RIGHTS 

Returns a substring from a specified string, extracting its rightmost 
characters. 






SPACES 


Returns a string of a specified number of spaces. 


STRINGS 

Returns a string of specified length whose characters all have the 
same ASCII code or equal the first character of a given string. 


I/O and Miscellaneous 
DATES 

Retrieves the current date. 


ENVIRONS 


Allows you to retrieve the specified Environment String from GW- 
BASIC’s Environment String Table. 


ERDEVS 

Holds the name of the device causing the error if it was a character 
device. 


HEX$ 


Returns a string which represents the hexadecimal value of the 
decimal argument. 


INKEYS 


Returns a one- or two-character string read from the keyboard or 
a null string if no character is pending at the keyboard. 
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INPUTS 

Returns a string of characters read from the keyboard or from a file. 


IOCTLS 

Returns a “Control Data” string from a Character Device Driver that 
is OPEN. 


|MKI$ | MKS$ | MKD$ 

Change numeric values to string type values. 


OCT$ 

Returns a string which represents the octal value of the decimal 
argument. 


SPC 

Skips n spaces in a PRINT, LPRINT, or PRINT# statement. 


STR$ 

Returns the string representation of the value of a specified numeric 
expression. 


TAB 

Tabs the cursor or the print head to a specified position, in PRINT, 
LPRINT, or PRINT # statements. 


TIMES 


Retrieves the current time. 








VARPTR$ 


Returns a character form of the memory address of the variable. 


ABS Function 


Returns the absolute value of a numeric expression. 


ABS( numexp ) 


Characteristics 

The returned value will always be positive or zero. 

Example 

Ok 

PRINT ABS(8*(-6)) 

48 

Ok 

Example 

DISTANCE = ABS(ST ART-FINISH) 


Example 

IF ABS(DELTA)< = LIMIT THEN STOP 
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ASC Function 



Returns the ASCII decimal code for the first character of a given string. 


ASC( stringexp ) 


Characteristics 

The ASC function returns the ASCII code (0-255) corresponding to the 
first character of the string stringexp . See Appendix C for a com¬ 
plete list of all ASCII codes. 

If stringexp is null, an ’’Illegal function call” error is returned. 

See the CHR$ function, for ASCII-to-string conversion. CHR$ is the 
inverse of the ASC function. 


Example 

The following example shows that the ASCII code for capital letter’T’ 
is 84. 


10 X$ = ’’TEST” 

20 PRINT ASC(X$) 

RUN 

84 

Ok 










ATN Function 


Returns the arctangent of the argument. 


ATN( numexp ) 


Characteristics 

The evaluation of ATN is performed in single precision, unless ID is 
supplied in the GWBASIC command line. 

The result is expressed in radians and falls in the range -PI/2 to PI/2 
(where PI = 3.141593). 


Example 

10 INPUT X 
20 PRINT ATN(X) 

RUN 
? 3 

1.249046 
Ok 


Example 

100 IF ATN(N) < PI/2.0 THEN PRINT ’’ANGLE 90 DEGREES” 
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AUTO Command 


Generates a line number after every carriage return. AUTO is only us¬ 
ed in immediate mode. 


AUTO [linenum][ , [increment]] 


Where 


SYNTAX ELEMENT 

MEANING 

linenum 

Is the line number used to commence numbering 
lines. 

increment 

Is the value added to a line number to produce the 
next line number. 


Characteristics 

AUTO begins numbering at linenum and increments each subse¬ 
quent line number by increment. The default for both values is 10. 
If linenum is followed by a comma but increment is not 
specified, the last increment specified in an AUTO command is assum¬ 
ed. If no preceding AUTO command was given, an increment of 10 
is assumed. 














If AUTO generates a line number that is already being used, an asterisk 
is displayed after the number to warn the user that any input will over¬ 
write the existing line. However, typing a carriage return immediately 
after the asterisk will save the line and generate the next line number. 


AUTO is terminated by typing CTRL BREAK (or CTRL C); the current line 
is not saved and GW-BASIC returns to command level. 


Examples 

AUTO 

Generates line numbers 10, 20, 30, 40 .... 

AUTO 100,20 

Generates line numbers 100, 120, 140 .... 

AUTO 200, 

Generates line numbers 200, 220, 240, 260, ... 

The increment is 20 because 20 was the increment in the last AUTO 
command. 

AUTO,15 

Generates line numbers 0,15,30,45, ... 


BEEP Statement 


Activates the bell. 


BEEP 


Characteristics 


PRINT CHR$(7); will send an ASCII BEL character, which will have 
the same effect. 
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Example 

130 IF X < 20 THEN BEEP 


BLOAD Command 



Loads a memory image file into memory. 


BLOAD {filespec\pathname] [, offset ] 


Where 


SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression that specifies the file to be 
loaded. If the device is omitted, the MS-DOS default 
drive is assumed. 

offset 

Is an integer expression in the range 0 to 65535. 
This is the offset into the segment declared by the 
last DEF SEG statement at which loading is to start. 














Characteristics 

The BLOAD and BSAVE statements allow you to load into memory, 
and save on a file, machine language routines. When these routines 
are resident in memory, they can be CALLed from your GW-BASIC 
program by a CALL statement. 

The BLOAD and BSAVE statements also allow you to load and save 
any portion of memory, for instance you can save and display screen 
images (specifying the screen buffer as the current segment by a DEF 
SEG statement). 

If offset is omitted, the offset specified at BSAVE is assumed, and 
the file is loaded into the same location from which it was saved. 

If offset is specified, a DEF SEG statement should be executed 
before the BLOAD. When offset is given, GW-BASIC assumes the 
user wants to BLOAD at an address other than the one saved. The 
last known DEF SEG address will be used. If no DEF SEG statement 
has been given, the GW-BASIC data segment will be used as the 
default (because it is the default for DEF SEG). 


Warning 

BLOAD does not perform an address range check. It is therefore possi¬ 
ble to load a file anywhere in memory. You must be careful not to load 
over GW-BASIC, or the operating system. 


Example 

10 DEF SEG ’Restore segment to GW-BASIC’s DS 
20 BLOAD ”B:PROG1 ”, &HF000 ’Load at offset F000 


Example 

10 'Load the screen buffer 

20 DEF SEG = &HB800 ’Point segment at screen buffer 
30 BLOAD ”FILE1 ”,0 ’Load FILE1 into screen buffer 
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Note the DEF SEG statement in 20 and the offset of 0 in 30: this 
guarantees that the correct address is used. 

An example under BSAVE illustrates how FILE1 was saved. 


BSAVE Command 


Saves sections of the main memory on the specified file. 


BSAVE {filespec | pathname j , offset , length 


Where 


SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression which specifies the name of 
the file to be saved, and optionally a device. If the 
device is omitted, the MS-DOS default drive is 
assumed. 

offset 

Is an integer expression in the range 0 to 65535. 
This is the offset into the segment declared by the 
last DEF SEG. 

length 

Is an integer expression in the range 1 to 65535, 
specifying the length of the memory image to be 
saved. 
















Characteristics 

A memory image file is a byte-for-byte copy of what is in memory. 

The BLOAD and BSAVE statements allow you to load into memory, 
and save on a file, machine language routines. When these routines 
are resident in memory, they can be CALLed from your GW-BASIC 
program by a CALL statement. 

The BLOAD and BSAVE statements also allow you to load and save 
any portion of memory, for instance you can save and display screen 
images (specifying the screen buffer as the current segment by a DEF 
SEG statement). 


A DEF SEG statement should be executed before the BSAVE. The 
last known DEF SEG address is always used for the save. 


Warning 

A BSAVE is not illegal in direct mode, even when the file saved to is 
protected. 


Example 

10 ’Save PROG1 

20 DEF SEG = &H6000 

30 BSAVE ”PROG1 ”,&HF000,256 

This examples saves 256 bytes starting at 60000:F000 in the file 
PROG1. 


Example 

10 ’Save the screen buffer 

20 DEF SEG = &HB800 ’Point segment at screen buffer 
30 BSAVE ”A:FILE1 ”,0,16384 ’Save screen buffer in FILE1 

The DEF SEG statement must be used to set up the Segment address 
to the screen buffer. The offset of 0 and the length 16384 specify that 
the entire 16K screen buffer is to be saved. 
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CALL Statement 


Transfers control to a machine language subroutine. CALL is usually 
used in a program. 


CALL numvar [ ( variable [ , variable]... ) ] 


Where 


SYNTAX ELEMENT 

MEANING 

numvar 

Is a numeric variable. It must equate to the star¬ 
ting address of the machine language routine. The 
address is an offset into the current memory seg¬ 
ment as set by the last DEF SEG statement. 

variable 

Is a numeric or string variable which serves as an 
argument to pass data between the main program 
and the machine language routine. 

Characteristics 


The CALL statement is one way to transfer program flow to an exter¬ 
nal subroutine. You can transfer control to an external subroutine also 
by use of the USR function. 













Example 


110 MYROUT = &HD000 
120 CALL MYROUT (l,J,K) 


CALLS Statement 


The CALLS statement is the same as the CALL statement with the 
exceptions given below under ’’Characteristics”. 


CALLS numvar [ ( variable [ , variable]... ) ] 



Where 


SYNTAX ELEMENT 


MEANING 


numvar 


Is a numeric variable. It contains the address that 
is the starting point in memory of the subroutine 
being CALLed 


variable 


Is a numeric or string variable which has to be pass¬ 
ed as an argument to the machine language 
subroutine. 
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Characteristics 

The CALLS statement is similar to CALL, except that the segmented 
addresses of all arguments are passed (CALL passes unsegmented 
addresses). CALLS should be used when accessing routines written 
with FORTRAN calling conventions, since all FORTRAN parameters 
are call-by-reference segmented addresses. 

CALLS uses the segment address defined by the most recently ex¬ 
ecuted DEF SEG statement to locate the routine being called. 


CDBL Function 


Converts a given numeric expression to a double precision number. 


CDBL( numexp ) 


Example 

10 A = 454.67 
20 PRINT A;CDBL(A) 

RUN 

454.67 454.6700134277344 
Ok 




















Transfers control and passes variables to another program. CHAIN 
is only used in a program. 

CHAIN [ MERGE ][ filespec \ pathname }[ , [ linenum ] [ , [ ALL ] 

[ , DELETE range ]]] 

Where 

SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression which specifies the name of 
the called program file and optionally the drive. If 
the drive is omitted the MS-DOS default drive is 
assumed. 

linenum 

Is a line number or an expression that evaluates 
to a line number in the called program. It is the star¬ 
ting point for execution of the called program. If it 
is omitted, execution begins at the first line. The 
parameter is not affected by a RENUM command. 

range 

' Is the range of line numbers to be deleted. These 
line numbers are affected by the RENUM 
command. 
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Characteristics 

IF... 

THEN... 

the MERGE option is 
used 

a MERGE operation is performed with the current 
program and the CHAINed program. The CHAIN- 
ed program must be an ASCII file. If any lines in 
the disk file have the same line numbers as lines 
in the program in memory, the lines from the file 
on disk will replace the corresponding lines in 
memory. (MERGEing may be thought of as ”inser- 
ting” the program lines on disk into the program 
in memory). The MERGE option leaves the files 
open, preserves the current OPTION BASE setting, 
and preserves variable types and user-defined 
functions, for use by the CHAINed program. 


User-defined functions should be placed before any 
CHAIN MERGE statements in the program. Other¬ 
wise, the user-defined functions will be undefined 
after the merge is complete. 

the MERGE option is 
omitted 

the CHAINing program is lost (except common 
variables) before loading the CHAINed program. 
CHAIN does not preserve variable types or user 
functions. Thus, any DEFtype or DEF FN 
statements containing shared variables must be 
repeated in the CHAINed program. 

the ALL option is 
used 

every variable in the current program is passed to 
the CHAINed program 
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IF... 

THEN... 


the ALL option is 
used and linenum is 
omitted 

two commas must be inserted between the filespec 
(or pathname) and the ALL option. For example: 

100 CHAIN ”NEXTPROG”,,ALL 

is correct, but: 

100 CHAIN ”NEXTPROG”,ALL 

is incorrect. In this case, GW-BASIC assumes that 
ALL is a variable name and evaluates it as a line 
number. 

the ALL option is 
omitted 

the current program must contain one or more 
COMMON statements to list the variables that are 
passed. 

the DELETE option is 
used 

a section of the current program will be deleted 
before loading the CHAINed program. 

DELETE is often used with MERGE and ’line’ op¬ 
tions, to load overlays. After an overlay is brought 
in, it is usually desirable to delete it so a new overlay 
may be brought in. 


Remarks 

Before running a CHAINed program, CHAIN carries out a RESTORE. 
This resets the pointer to the beginning of the internal data file. 
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Example 1 


CHAIN is used in different ways in two programs below. In the first 
the two string arrays are dimensioned, and declared, as common 
variables. When the first program gets to line 80, it chains to the se¬ 
cond program (PROG 2), which loads the two elements of the B$ ar¬ 
ray. At line 80 of PROG 2, control chains back to the first program, 
beginning execution at line 90. This process can be observed through 
the descriptive text that prints as the programs execute. 

10 REM THIS PROGRAM DEMONSTRATES CHAINING USING 
COMMON TO PASS VARIABLES 
20 REM SAVE THIS MODULE ON DISK AS ”PROG1” 

USING THE A OPTION. 

30 DIM A$(2),B$(2) 

40 COMMON A$0,B$0 

50 A$(1) =’’VARIABLES IN COMMON MUST BE ASSIGNED” 
60 A$(2) =’’VALUES BEFORE CHAINING.” 

70 B$(1) = B$(2) =”” 

80 CHAIN ”PROG2” 

90 PRINT: PRINT B$(1): PRINT: PRINT B$(2): PRINT 
100 END 


10 REM THE STATEMENT ’’DIM A$(2), B$(2)” 

MAY ONLY BE EXECUTED ONCE. 

20 REM HENCE, IT DOES NOT APPEAR IN THIS 
MODULE 

30 REM SAVE THIS MODULE ON THE DISK AS ”PROG2” 
USING THE A OPTION. 

40 COMMON A$(), B$() 

50 PRINT: PRINT A$(1); A$(2) 

60 B$(1) = ’’NOTE HOW THE OPTION OF SPECIFYING 
A STARTING LINE NUMBER” 

70 B$(2) = ’’WHEN CHAINING AVOIDS THE DIMENSION 
STATEMENT IN ’PROG1 ’.” 

80 CHAIN ”PROG1 ”, 90 
90 END 






Example 2 


In the following example, the MERGE, ALL, and DELETE options are 
illustrated. After A$ is loaded in the first program, control chains to 
line 1010 of the second. At the second program’s line 1040, it chains 
to line 1010 of the third program, keeping all variables and deleting 
all the second program’s lines. Control passes to the third program. 
This process can be observed through the descriptive text that prints 
as the programs execute. 

10 REM THIS PROGRAM DEMONSTRATES CHAINING USING 
THE MERGE, ALL, AND DELETE OPTIONS 

20 REM SAVE THIS MODULE ON THE DISK AS ‘MAINPRG” 

30 A$ = “MAINPRG” 

40 CHAIN MERGE “OVRLAY1”, 1010, ALL 

50 END 

1000 REM SAVE THIS MODULE ON THE DISK AS “OVRLAY1 ” 
USING THE A OPTION. 

1010 PRINT A$; “HAS CHAINED TO OVRLAY1.” 

1020 A$ = “OVRLAY1” 

1030 B$ = “OVRLAY2” 

1040 CHAIN MERGE “OVRLAY2”, 1010, ALL, DELETE 1000-1050 

1050 END 

1000 REM SAVE THIS MODULE ON THE DISK AS “OVRLAY2” 
USING THE A OPTION. 

1010 PRINT A$; “HAS CHAINED TO”; 

1020 END 
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CHDIR Command 

Changes the current directory. 


CHDIR pathname 


Where 


SYNTAX ELEMENT 

MEANING 

pathname 

Is a string expression identifying the new directory 
which is to be the current directory 

Examples 

ROOT 

/ \ 

SALES ACCOUNTS 

/ /\ 


FRED AMOS ANDY 
/ 

WILMA 













Assuming that the diskette on drive B has the directory structure il¬ 
lustrated above, let us change the current directory from ROOT to AC¬ 
COUNTS: 


CHDIR ”B: ACCOUNTS’’ 

ACCOUNTS is now the current directory on drive B. 

To change the current directory from ACCOUNTS to ANDY use: 

CHDIR ’ANDY” 

Remarks 

Avoid nesting directories too deeply as a result of using MKDIR and 
CHDIR repeatedly. 

Possible Errors 

’’Bad file name” 

’’Path not found” 

’’Path/File Access error” 
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CHR$ Function 


Returns a one-character string whose ASCII decimal code is the value 
of the argument. 


CHR$( n ) 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression which must be in the range 
0 to 255. It represents an ASCII code. If it is out¬ 
side the specified range, an ’’Illegal Function Call” 
is returned. 


Characteristics 

CHR$ is normally used to send a special character to an output device. 
For instance, the BEL character (CHR$(7)) could be sent as a preface 
to an error message, or a form feed (CHR$(12)) could be sent to clear 
a terminal screen and return the cursor to the home position. 


Examples 

100 PRINT CHR$(7) ’BEEP 
150 PRINT CHR$(LINEFEED%) 

200 IF CHR$(INP(IN.PORT°/o)) = ”A” THEN GOSUB 100 











CINT Function 


Converts any numeric argument to an integer by rounding the frac¬ 
tional portion. 


CINT( numexp ) 


Characteristics 

If numexp is not in the range -32768 to 32767, an "Overflow” er¬ 
ror occurs. 

If the fractional portion of numexp is > = .5 the integer part is 
rounded up; otherwise a truncation occurs. 

See the CDBL and CSNG functions for details on converting numbers 
to the double precision and single precision data type, respectively. 
See also the FIX and INT functions, both of which return integers. 


Examples 

Ok 

PRINT CINT(45.67) 

46 

Ok 

PRINT CINT(-3.71) 

-4 

Ok 
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CIRCLE Statement 

Draws a circle (or an ellipse) with the specified center and radius 
(Graphics mode only). 


CIRCLE [ STEP ] ( x , y), radius [ , color [, start, end [, aspect ]]] 


Where 


SYNTAX ELEMENT 

MEANING 

*,y 

Are numeric expressions, specifying the coor¬ 
dinates of the center of the circle (or ellipse). They 
may be absolute coordinates, or relative coor¬ 
dinates (if STEP is included). 

radius 

Is a numeric expression returning a positive integer 
value giving the value of the radius of the circle, 
or the major axis of the ellipse. It is measured in 
the horizontal direction if aspect < 1, and in ver¬ 
tical direction if aspect > 1. The value of the radius 
is interpreted as pixels if the WINDOW statement 
has not been executed, otherwise it is interpreted 
as screen coordinates. 

► 

















SYNTAX ELEMENT 

MEANING 

color 

Is an integer expression in the range 0 to 3. It is 
the color number of the circumference of the cir¬ 
cle (or ellipse). 

In Medium Resolution color choses the color from 
the currently selected palette. In High and Super 
Resolution, 0 or 2 indicates black, and 1 or 3 in¬ 
dicates white. 

If color is omitted, the color specified for the 
gforeground parameter in the COLOR statement 
is assumed; if this parameter has also been omit¬ 
ted, color 3 in Medium Resolution and color 1 in 
High and Super Resolutions, are assumed. 

start, end 

Are numeric expressions specifying angles in ra¬ 
dians. The range is from -2*PI to 2*PI, where PI 
= 3.141593. They specify where the drawing of the 
arc of the circle (or ellipse) will begin and end. 

aspect 

Is a numeric expression returning a positive real 
value. Due to the difference between the spacing 
of pixels on the x-and y-axis of the screen, you must 
specify a value of aspect to draw a true circle with 
different monitors. The default value of ’aspect’ is 
5/6 in medium and super resolution and 5/12 in 
high resolution. This value produces a circle with 
the standard monitor. 
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Drawing Circles and Ellipses 


The CIRCLE statement draws circles if you do not specify the 
aspect parameter, and ellipses if you specify a value of aspect dif¬ 
ferent from the default value (5/6 in Medium and Super Resolution, 
and 5/12 in High Resolution). 


The aspect may be thought of as a fraction, which specifies the 
number of pixels necessary in order to have equal lengths along the 
two axes. The numerator specifies the number of pixels along the x- 
axis and the denominator specifies the number of pixels along the 
y-axis. 

If aspect is less than one, then radius is measured in pixels 
in the horizontal direction i.e., it is the x-radius. In this case GW-BASIC 
draws ellipses with the same width, and varies the height as the 
parameter varies. 


If aspect is greater than one, the y-radius is given, and GW-BASIC 
draws ellipses with the same height and varies the width, as the 
parameter varies. 
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It is not possible to transform a circle (drawn with the CIRCLE state¬ 
ment) into an ellipse using the WINDOW and VIEW statements (i.e. 
by varying the ratio of the sides of the window); it is possible to achieve 
this if the circle has been drawn (using the LINE statement) as a regular 
polygon with a large number of sides. 


Example 

10 SCREEN 1 


100 CIRCLE (100,150),50,,,,5/18 
will draw a horizontal ellipse with an x-radius of 50 pixels. 


Drawing Arcs 

The CIRCLE statement can simply draw part of a circle (or ellipse) i.e. 
an ’’arc”. 

To draw an arc you must enter the start and end parameters. 
They specify the first and the second arc endpoint in radians. 

The angles are measured from the x-axis in a counterclockwise direc¬ 
tion, as shown in Figure 8-2. 

For example, the following statement specifies just a quarter of a circle: 

10 CIRCLE (100,150),50,1,0,3.141593/2 

The angles must be measured in radians. If you have the angles in 
degrees, you must convert them to radians before executing the CIR¬ 
CLE statement. To convert from degrees to radians, multiply by 
0.0174532. 
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Fig. 8-2 Arc of a Circle 


Drawing Rays 

The CIRCLE statement can draw a ray from the center of the arc to 
either arc endpoint. 

A negative endpoint generates a ray to that endpoint. The endpoint 
-0 is not treated as a negative endpoint. To circumvent this limitation, 
use a small negative number (e.g. -0.001 instead of -0). When both 
endpoints are negative, both rays are drawn. The minus sign does not 
affect the arc itself, i.e. the angles will be treated as if they were positive. 
Note that this is different from adding 2*Pi (where Pi is 3.141593). The 
start angle may be greater or less than the end angle. For example: 

10 SCREEN 1 


100 CIRCLE (100,150),50,1,-0.001,-3.141593/2 
will draw a quarter of a circle delimited by two rays. 











Last Point Referenced 


The last point referenced after a circle (or ellipse) has been drawn is 
the center of the circle (or ellipse). 


STEP Option 

Coordinates can be absolute, or relative (if the STEP option is 
specified). Relative coordinates are interpreted as relative to the last 
referenced point. 

For example, if the last point referenced was 100,50, then: 
both: 

CIRCLE (200,200),50 


and: 

CIRCLE STEP (100,150),50 


will draw a circle at 200,200 with radius 50. The first example uses 
absolute coordinates; the second uses relative coordinates. 


Example 

The following example draws three intersecting circles and colors the 
area of intersection. 


5 

10 

20 

30 

40 

50 

60 


SCREEN 1 
COLOR 0,0,3,0 
CLS 

CIRCLE (100,120),90 
CIRCLE (150,130),120 
CIRCLE (250,120),100 
PAINT (180,120) 
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CLEAR Command 

Clears all numeric variables to zero, all string variables to null, closes 
all open files and cancels the effect of any DEF or DIM statements. 
Options set the maximum memory available for use by GW-BASIC, 
and the amount of stack space. 


CLEAR [ , [memory][ , stack]] 


Where 


SYNTAX ELEMENT 

MEANING 

memory 

Is an integer expression representing a memory 
location which, if specified, sets the top of memory 
available to GW-BASIC (i.e. the maximum exten¬ 
sion of the GW-BASIC Data Segment). The max¬ 
imum value allowed is 65536. The default value (i.e. 
when the parameter is omitted or equals 0) is the 
maximum current value as specified in the 
GW-BASIC command (or 65536 if the GWBASIC 
command does not specify a value). 

stack 

Is an integer expression whose value sets aside 
stack space for GW-BASIC. The default is 128 
bytes or one-eighth of the available memory, 
whichever is smaller. 




















Characteristics 


The memory parameter should be specified to reserve sufficient 
space in memory for machine language routines. The stack parameter 
is used to increase the stack space; the amount of space reserved 
may be critical when a program has several nested GOSUB 
statements, several nested FOR...NEXT loops and/or PAINT 
statements which paint complex figures. 

If there is not enough space for the program, or for the stack, you will 
get an “Out of Memory” error. 

GW-BASIC allocates string space dynamically. An ’’Out of string 
space” error occurs only if there is no free memory left for GW-BASIC 
to use. 


The CLEAR statement does not modify the program in memory but 
performs the following actions: 

• Closes all files 

• Clears all COMMON variables 

• Resets the stack and frees the space reserved for strings 

• Resets all simple numeric variables and numeric array elements to 
zero 

• Resets all simple string variables and string array elements to null 

• Releases all disk buffers 


• Resets all DEF FN, DEFINT/SNG/DBL/STR, DEF SEG and 
USR statements 


DEF 
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Examples 

CLEAR 

CLEAR ,32768 
CLEAR ,,2000 
CLEAR ,32768,2000 








CLOSE Statement 


Terminates I/O to a file or device. CLOSE is usually used in a program. 


CLOSE [[ # ] filerum [ , [ # ] filerum ]...] 


Where 


SYNTAX ELEMENT 

MEANING 


filenum 

Is the number under which the file was OPENed. 
A CLOSE with no arguments closes all open files. 


Characteristics 

The association between a particular file and file number terminates 
upon execution of a CLOSE statement. The file may then be reOPENed 
using the same or a different file number; likewise, a file number may 
now be reused to OPEN any file. 

A CLOSE for a sequential output file writes the final buffer of output. 

The END statement and the NEW command always close all disk files 
automatically (STOP does not close disk files). 
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Example 

To read the data in a sequential file open for output or append, you 
must first CLOSE the file and then re-OPEN it in ”1” mode. 


100 CLOSE #1 

110 OPEN ”1”, #1, ’’DATA” 


CLS Statement 


Erases all of the screen or a window. 


CLS 


Characteristics 


CLS in text mode clears the entire screen to the current text 
background color. If a viewport has been defined, the current viewport 
only will be cleared to the graphics background color. 

Remarks 

CLS not only erases all or part of the screen, but also returns the cur¬ 
sor to the upper left-hand corner of the screen (in Text Mode). 

If you are in Graphics Mode, CLS makes the ’’last referenced point” 
the center of the screen. 


The screen can also be cleared by pressing CTRL HOME , or by 
modifying the screen mode using the SCREEN statement, or the width 
using the WIDTH statement. 


Examples 


5 COLOR 10,3 
10 CLS 


Clears the screen to cyan. 











COLOR Statement (SCREEN 0) 


Sets the text foreground and background colors in Text Mode. 


COLOR [foreground] [ , background] [ , dummy]] 


Where 


SYNTAX ELEMENT 

MEANING 

foreground 

Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 31. Values greater 
than 15 are interpreted modulo 16. It selects the 
character foreground color. 

background 

Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 15, but it is inter¬ 
preted modulo 8, thus only values from 0 to 7 are 
taken into consideration. It selects the character 
background color. 
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SYNTAX ELEMENT 

MEANING 

dummy 

Is a parameter allowed for compatibility with other 
BASICS. It will have no effect. It may specify screen 
border color on other systems. 


Characteristics (Color Text Mode) 

If you are using a color system the following colors are available for 
foreground: 


0 Black 

1 Blue 

2 Green 

3 Cyan 

4 Red 

5 Magenta 

6 Yellow 

7 White 


8 Gray 

9 Light Blue 

10 Light Green 

11 Light Cyan 

12 Light Red 

13 Light Magenta 

14 Light Yellow 

15 High-intensity White 


To make characters blink for a specific color, you should set 
foreground equal to 16 plus the color number. 


Only colors 0 through 7 are allowed for background . 

Characteristics (B/W Text Mode) 

In a monochrome system the following values can be used for 
foreground. 

• 0 
• 1 

• 2-6 

• 7 


Black 

Underlined character with white foreground 
Shades of gray 

White / ,-v 

\° ftl, 7 










Adding 8 to the number of the desired color gives you the color in 
high-intensity. 

To make character blink, add 16 to the number of the desired color. 
The following values are allowed for background : 

• 0-1 Black 

• 2-6 Shades of gray 

• 7 White 


Remarks 

Foreground and background colors may be equal. In this case any 
character displayed is invisible. Changing the foreground or 
background color will make subsequent characters visible again. 

Any parameter may be omitted. Omitted parameters assume the old 
value. 

Upon initialization, the default values are: 

• foreground = 7 (White) 

• background = 0 (Black) 

That is, if no COLOR statement exists in your program, the system 
assumes: 

COLOR 7,0 

Examples 

100 COLOR 0,2 

This sets a black foreground on a green background with a color screen 
and a black foreground on a gray background, with a black and white 
screen. 
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150 COLOR 15,1 

This sets a high-intensity white on a blue background with a color 
screen, and a high-intensity white on a black background with a black 
and white screen. 


Possible Errors 

• If the COLOR statement ends in a comma (,), a ’’Missing operand” 
error is returned. For example: 

COLOR 2, 
is invalid. 

• Any parameters outside the specified ranges will result in an ’’Il¬ 
legal function call” error. In this case, previous values are retained. 


COLOR Statement (SCREEN 1) =^= 


Defines the palette background and foreground colors in Medium 
Resolution Mode. In addition, the default graphics foreground and 
background colors, and the text foreground color can be defined. 


COLOR [i background ][ , [palette][ , [gforeground][ , [gbackground] 
[ , tforeground]]]] 








Where 


SYNTAX ELEMENT 


MEANING 


background 


Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 31. Values greater 
than 15 are taken modulo 15. It represents the col¬ 
or code for the character background. 


0 Black 

1 Blue 

2 Green 

3 Cyan 

4 Red 

5 Magenta 

6 Yellow 

7 White 


8 Gray 

9 Light Blue 

10 Light Green 

11 Light Cyan 

12 Light Red 

13 Light Magenta 

14 Light Yellow 

15 High-intensity White 


palette 


It also specifies the color for color number 0 that 
may be given with graphics statements. A value 
between 16 and 31 (interpreted modulo 15), 
specifies that foreground colors (text and color 
number 1,2 and 3) are displayed with high inten¬ 
sity. It defaults to 0 (black). 


Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 through 255. This 
selects one of two palettes. A graphics statement 
can specify a foreground color through a color 
number (0,1,2 or 3) which selects the desired col¬ 
or from the choice provided by the active palette. 
If the color number is 0, the color specified by 
background will be selected. 


Palette Color 0 Color 1 Color 2 Color 3 
0 background green red yellow 

1 background cyan magenta white 

Palette 1, the default, is selected when palette is 
an odd number, otherwise palette 0 is selected. 


8-62 


GW-BASIC INTERPRETER USER GUIDE 











COMMANDS, STATEMENTS AND FUNCTIONS 


SYNTAX ELEMENT 

MEANING 

gforeground 

Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 3. This specifies 
the graphics foreground which is the default color 
number when no color parameter is specified in a 
graphics statement. If gforeground is omitted, 3 
is assumed. The graphics foreground is always set 
to the default value (3) when the SCREEN state¬ 
ment selects new screen mode 1. 

gbackground 

Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 3. This specifies 
the graphics background; i.e., the color used when 
a graphics viewport is cleared with just CLS. The 
default value is 0, which is always selected when 
a new screen mode is selected. 

tforeground 

Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 3. It selects the 
character foreground color. It defaults to 3. 















Characteristics 

When you enter a CIRCLE, DRAW, LINE, PAINT, PRESET, or PSET 
statement, you can specify a color number of 0, 1, 2, or 3. This 
parameter selects the color from the current ’’palette’ as defined by 
the COLOR statement. 

If you do not specify a color number, the default is the graphics 
foreground (i.e. the value of gforeground, or 3 if gforeground has not 
been specified). 

When you display text the character foreground will be set by 
tforeground (that defaults to color number 3), and the character 
background will be set by background (that defaults to 0, i.e. black). 

Any parameter may be omitted in the COLOR statement. Omitted 
parameters assume the old value. 

Upon initialization the default values are: 

• background = 0 (black) 

• palette = 1 (high-intensity, cyan, magenta and white) 

• gforeground = 3 (high-intensity white) 

• gbackground = 0 (black) 

• tforeground = 3 (high-intensity white) 

That is, if no COLOR statement exists in your program, the system 
assumes: 

COLOR 16, 1, 3, 0, 3 
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Examples 

10 SCREEN 1,0 
20 COLOR 10,1,2,0 

Sets the character background to light green, selects palette 1 (Cyan, 
Magenta, White), sets the graphics foreground to magenta, and 
graphics background to light green. 

100 COLOR ,0 

The character background stays light green and palette 0 (green, red, 
yellow) is selected. 


COLOR Statement (SCREEN 2 and 3) 


Defines the foreground color for text and graphics, in High and Super 
Resolution Modes. 


COLOR [foreground] 









Where 


SYNTAX ELEMENT 

MEANING 

foreground 

Is a numeric expression rounded to the nearest in¬ 
teger. It must be in the range 0 to 15. Larger values 
are interpreted modulo 16. This specifies the text 
and graphics foreground color according to the 
following: 

0 Black 8 Gray 

1 Blue 9 Light Blue 

2 Green 10 Light Green 

3 Cyan 11 Light Cyan 

4 Red 12 Light Red 

5 Magenta 13 Light Magenta 

6 Yellow 14 Light Yellow 

7 White 15 High-intensity White 

The color upon entry into High Resolution or Super 
Resolution Mode is high-intensity white. 


Characteristics 

Only one foreground color can be displayed at any one time. Chang¬ 
ing the foreground color results in all current foreground being chang¬ 
ed to the color specified. The background color is always black. 

Example 

10 SCREEN 2 
20 COLOR 4 

Results in High Resolution Mode with a foreground of red. 

30 SCREEN 3 
40 COLOR 5 

Results in Super Resolution Mode with a foreground color of magenta. 
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COM(n) Statement 



COM(n) ON enables, COM(n) OFF disables, and COM(n) STOP 
suspends event trapping of communications activity on the specified 
channel. 


COM( n ) [ON | OFF |STOP } 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression that specifies the number 
of the communications channel. It may be 1 or 2. 
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To Enable or Disable COM(n) Trapping 


IF... 

THEN... 

a COM(n) ON is 
executed 

communications event trapping is enabled. While 
trapping is enabled, and if a non-zero line number 
is specified in the ON COM(n) GOSUB statement, 
GW-BASIC checks between every statement to see 
if activity has occurred on the communications 
channel. If it has, the ON COM(n) GOSUB state¬ 
ment is executed. 

a COM(n) OFF is 
executed 

communications event trapping is disabled. If an 
event takes place, it is not remembered. 

a COM(n) STOP is 
executed 

communications event trapping is suspended. If an 
event occurs it is remembered, and ON COM(n) will 
be executed as soon as trapping is enabled. 

an ON COM(n) 

GOSUB is executed 

communications event trapping is suspended. 

an error trap takes 
place 

all trapping is automatically disabled (including ER¬ 
ROR trapping). 


Example 

10 COM(1) ON 

Enables error trapping of communications activity on channel 1 
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COMMON Statement 



Defines a common area which is not erased by the CHAINed program, 
and allows you to pass variables from one program to another. 
COMMON should only be used in a program. 


COMMON variable[ , 

variable]... 

Where 

SYNTAX ELEMENT 

MEANING 

variable 

Is the name of a numeric or string variable which 
is required to be passed to the CHAINed program. 
For array variables place a set of parentheses ”()” 
after the variable name. 



Characteristics 


The COMMON statement is used in conjunction with the CHAIN state¬ 
ment. COMMON statements may appear anywhere in a program, 
though it is recommended that they appear at the beginning. 


Variables specified in COMMON statements are allocated in the com¬ 
mon area starting from the beginning and in the order in which they 
appear in the program. 
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The CHAINed program need not specify, through the use of COMMON 
statements, the common variables specified by the CHAINing program. 
The CHAINed program will use these variables with the same names 
specified in the CHAINing program. Each type definition statement (DE- 
FINT, DEFSNG, DRFDBL, DEFSTR) referring to common variables, 
must precede the associated COMMON statements and must be 
repeated in the CHAINed program. 

Common variables must always be initialized within the CHAINing pro¬ 
gram. Common arrays must be explicitly described by DIM statements 
in the CHAINing program (but not in the CHAINed program, otherwise 
a ’’Duplicate definition” error occurs). The DIM statements must be 
written before the associated COMMON statements. 


Example 

10 REM PG1 

20 COMMON A1,B1,C1,D1$ 


80 CHAIN ”A:PG2” 

90 END 

10 REM PG2 
20 PRINT A1,B1,C1,D1$ 


120 END 

The above example shows that the CHAINed program need not 
specify, through the use of COMMON statements, the common 
variables specified by the CHAINing program. 

In our example the values of the variables A1, B1, Cl, and D1$ in the 
program PG1 are passed to the CHAINed program PG2, which may 
display them (see Statement 20). 
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Example 

10 REM PG1 
20 DEFDBLC 
30 COMMON A1,B1,C1,D1$ 


90 CHAIN ”A:PG2” 
100 END 

10 REM PG2 
20 DEFDBL C 


130 END 

Each type definition statement (DEFINT, DEFSNG, DEFDBL, DEFSTR) 
referring to common variables, must precede the associated COMMON 
statement and must be repeated in the CHAINed program. (Note the 
statements DEFDBL, both with PG1 and PG2.) 


Example 

10 REM PROG RAMI 
20 COMMON A$,B$,C$ 
30 COMMON A$,A1 


100 END 

It is not good programming practice to repeat the same variable name 
(in this case A$) either in different COMMON statements of the same 
program, or in the same COMMON statement. In any case multiple 
definitions are equivalent to a single definition. 



Example 


10 REM PG1 
20 DIM A1 (15,20) 

30 COMMON AIQ.BI.CI 


100 CHAIN ”A:PG2” 
110 END 

10 REM PG2 


50 PRINT A1 (1,1) 


90 END 

This example shows the definition and transfer of an array variable, 
using the COMMON statement, to the chained program. 


Example 


10 REM modi 
20 A = 1:B = 2 
30 COMMON A,B 
40 GOTO 60 
50 COMMON C 
60 CHAIN ”mod3” 


10 

20 

30 

40 

50 

60 


REM mod2 


A = 1:B = 2 


COMMON A 
GOTO 60 
COMMON B 
CHAIN ”mod3 


»> 



10 REM mod3 
20 PRINT A;B 
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The COMMON statement is a declarative statement, thus it allocates 
a common area even if control of execution does not pass through it. 

For example, when executing program ’’modi” an ’’Illegal function 
call in 50” is issued, as variable C has not been initialized. When ex¬ 
ecuting program ”mod2” instead, program ”mod3” is CHAINed: it 
displays both A and B variables, even if statement 50 of ”mod2” is 
jumped over. 


CONT Command 


Resumes program execution after a CTRL BREAK has been typed 
or a STOP or END statement has been executed. CONT should only 
be used in immediate mode. 


CONT 


Characteristics 

Execution resumes at the point where the break occurred. If the break 
occurred after a prompt from an INPUT statement, execution continues 
with the reprinting of the prompt (”?” or prompt string). 

CONT is usually used in conjunction with STOP for debugging. When 
execution is stopped, intermediate values may be examined and 
changed using direct mode statements. Execution may be resumed 
with CONT or a direct mode GOTO, which resumes execution at a 
specified line number. 

CONT may not be used to continue execution after an error has oc¬ 
curred. CONT is also invalid if the program has been modified during 
the break. 
















Example 


10 INPUT A,B 
20 TEMP= A*B 
30 STOP 

40 FINAL = TEMP+ 300: PRINT FINAL 

RUN 

? 32 , 2.4 
Break in 30 
Ok 

PRINT TEMP 

76.8 
Ok 

CONT 

376.8 
Ok 


COS Function 


Returns the cosine of the argument. 


COS( numexp ) 


Characteristics 

The argument numexp represents the angle in radians. 

The calculation of the COS function is performed in single precision, 
unless ID is supplied in the GWBASIC command line. 
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Example 

10 X = 2*COS(.4) 
20 PRINT X 
RUN 
1.842122 
Ok 


CSNG Function 


Converts any numeric argument to a single precision number. 


CSNG( numexp ) 


Remarks 

See the CINT and CDBL functions for converting numbers to the in¬ 
teger and double precision data types, respectively. 


Example 

10 A# = 975.3421 
20 PRINT A#; CSNG(A#) 

RUN 

975.3421020507813 975.3421 
Ok 










CSRLIN Function 


Returns the current line (row) position of the cursor. 


CSRLIN 


Characteristics 

CSRLIN returns an integer value in the range 1 to 25. To return the 
current column position use the POS function. 


Example 

10 Y = CSRLIN ’Record current line. 

20 X = POS(O) ’Record current column. 

30 LOCATE 24,1 :PRINT ’’HELLO” ’Print HELLO on last line. 
40 LOCATE Y,X ’Restore position to old line, column. 


CVI, CVS, CVD Functions 


Converts string values to numeric values. 
Syntax 1 


CVI( 2-byte-string ) 
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Syntax 2 


CVS( 4-byte-string) 


Syntax 3 


CVD( 8-byte-string ) 


Characteristics 

These functions are useful for converting strings into numbers when 
dealing with random files. 

CVI converts a 2-byte-string to an integer. 

CVS converts a 4-byte-string to a single precision number. 

CVD converts an 8-byte-string to a double precision number. 

See also ”MKI$, MKS$, MKD$” functions, later in this chapter. 

Example 


70 FIELD #1,4 AS N$, 12 AS B$, ... 
80 GET # 1 
90 Y = CVS(N$) 












DATA Statement 


Creates an internal file, i.e., a sequence of data belonging to the pro¬ 
gram. Each data item will then be assigned to a program variable by 
a READ statement. A DATA statement should only be used in a 
program. 


DATA constant , constant]... 


Where 

SYNTAX ELEMENT 

MEANING 

constant 

Is a numeric or string constant. Any numeric for¬ 
mat (i.e., integer, hexadecimal, octal, single or dou¬ 
ble precision) is acceptable for numeric constants. 
String constants in DATA statements must be sur¬ 
rounded by double quotation marks only if they con¬ 
tain commas, colons, or significant leading or 
trailing spaces. Otherwise, quotation marks are not 
needed. 
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Characteristics 

DATA statements are non-executable and may be placed anywhere 
in the program. A DATA statement may contain as many constants 
as will fit on a line (separated by commas). Any number of DATA 
statements may be used in a program. 

A DATA statement in a program need not correspond to a specific 
READ statement. This is because before program execution, a data 
file is created. It contains all the values of all the DATA statements 
in the program in line number sequence. When the program is ex¬ 
ecuted, READ takes its values from this file. 

The data-type of an entry in the data sequence must correspond to 
the type of the variable to which it is to be assigned; i.e., numeric 
variables require numeric constants as data (conversion from one 
numeric type to another is allowed, for example you may have a single 
precision floating point constant associated with an integer variable) 
and string variables require quoted or unquoted strings as data. 

A quoted string is required if the string contains commas (e.g. ’’BIRM¬ 
INGHAM,”) or initial or final blanks (e.g. ” BIRMINGHAM”). 

DATA statements may be re-read from the beginning by use of the 
RESTORE statement. 


Example 

Ok 

10 PRINT ’’CITY”, ’’STATE”, ’’ZIP” 

20 READ C$,S$,Z 

30 DATA ’’BIRMINGHAM,’’.ALABAMA,12345 
40 PRINT C$,S$,Z 

RUN 

CITY STATE ZIP 

BIRMINGHAM, ALABAMA 12345 

Ok 






DATE$ Function and Statement 


Retrieves the date (as a function), or sets the date (as a statement). 
Syntax 1: As a function 


stringvar = DATE$ 


Syntax 2: As a statement 


DATES = stringexp 


Characteristics 

As a function, the current date is fetched and assigned to the string 
variable stringvar . The DATES function may also be used in any 
string expression in a LET or PRINT statement. 

As a statement, the current date is set. In this case DATES is the target 
of a string assignment. 

The date may also have been set by MS-DOS prior to entering 
GW-BASIC. 
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Remarks 

If stringexp is not a valid string, a ’’Type mismatch” error will result. 
Previous values are retained. 


For stringvar = DATE$, DATE$ returns a 10 character string in 
the form ” mm-dd-yyyy" where mm is the month (01 to 12), dd is the 
day (01 to 31) and yyyy is the year (1980 to 2099). 

For DATES = stringexp, stringexp may be one of the follow¬ 
ing forms: 

” mm-dd-yy ” 
or 

"mm/dd/yy” 

or 

"mm-dd-yyyy” 

or 

"mm/dd/yyyy" 


If the month or day is specified by the use of only one digit, GW-BASIC 
assumes a 0 (zero) in front of it. If the year is specified by the use of 
one digit (y), GW-BASIC assumes the year to be 200y; if two digits 
are specified (yy), the year will be assumed to be 19yy. 


If any of the values are out of range or missing, an ’’Illegal function 
call” error is issued. Any previous date is retained. 


Example 

DATE$ = ”01-01-83” 

Ok 

PRINT DATE$ 

01-01-1983 

Ok 
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DEF FN Statement 


Defines and names a user-written function. A DEF FN statement may 
only be used in a program. 


DEF FNname[ ( argument[ , argument]... ) ] = expression 


Where 


SYNTAX ELEMENT 

MEANING 

• 

name 

Is a legal variable name. No blanks may be inserted 
between FN and name and the first character of 
name must be a letter. 

argument 

Is a ’’dummy” variable that is to be replaced by the 
corresponding argument value when the function 
is called. 

expression 

Is an expression that performs the operation of the 
function. 

The type of expression must agree with the type 
(numeric or string) of the function, specified by 
name. 
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Characteristics 

In the DEF FN statement, variable names serve only to define the func¬ 
tion; they do not affect program variables that have the same name. 
A variable name used in a function definition may or may not appear 
in the argument list. If it does, the value of the parameter is supplied 
when the function is called. Otherwise, the current value of the pro¬ 
gram variable is used. 

The variables in the argument list represent, on a one-to-one basis, 
the argument variables or values that are to be given in the function call. 

User-defined functions may be numeric or string. The type of the func¬ 
tion is specified by name . The type of the expression must match 
the type of the function, otherwise a ’’Type mismatch” error occurs. 
If the function is numeric the value of the expression is forced to that 
type before the function value is returned. 

If a DEF FN statement has not been executed before the function it 
defines is called, an ’’Undefined user function” error occurs. 


Example 


400 Ft = 1:S = 2 

410 DEF FNAB(X,Y) = X a 3/Y a 2 
420 T = FNAB(R,S) 


Line 410 defines the function FNAB. The function is called in line 420. 
When executed, the variable T will contain the value (R a 3) divided 
by (S a 2), that is .25. 




DEF SEG Statement 


Assigns the starting address of the current ’’segment” of memory. 
DEF SEG is usually used in a program. 


DEF SEG [ = address] 


Where 


SYNTAX ELEMENT 

MEANING 


address 

Is a numeric expression returning an unsigned in¬ 
teger in the range 0 to 65535. The address 
specified identifies the segment start address us¬ 
ed by BLOAD, BSAVE, PEEK, POKE, DEF USR, 
and CALL. 
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Characteristics 


IF... 

THEN... 

address is omitted 

the current segment is set to GW-BASIC’s Data 
Segment. This is the initial default value. 

address is specified 

the binary value is shifted left 4 bits (i.e., if address 
is in hexadecimal a zero is appended) to form the 
current segment start address. 

you enter a value out¬ 
side the 0-65535 
range 

an ’’Illegal function call” error results. The previous 
value will be retained. 

This is the only check that GW-BASIC makes. 
Since whatever address is given, within the range, 
is considered valid, it is the responsibility of the user 
to ensure that the address is really valid, i.e. so that 
subroutines are not called from incorrect addresses 
and important areas of memory are not overwritten. 

you do not separate 
DEF and SEG by at 
least one blank 

GW-BASIC would interpret DEFSEG as the name 
of a variable. For instance: 

100 DEFSEG = 150 

would assign the value 150 to the variable DEFSEG. 












Examples 

10 DEF SEG = &HB800 
Set segment to Screen buffer 

100 DEF SEG 

Restore segment to GW-BASIC’s DS. 

Note that in statement 10 the screen buffer is at absolute address 
B8000 hex, as the last hexadecimal digit is omitted in the DEF SEG 
statement. 


DEF USR Statement 


Enables access to a machine language subroutine by specifying the 
starting address. The subroutine may be subsequently called by the 
associated USR function. DEF USR is usually used in a program. 


DEF USR [n] = offset 
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Where 

SYNTAX ELEMENT 

MEANING 

n 

May be any digit from 0 to 9. The digit corresponds 
to the number of the USR routine whose address 
is being specified. If n is omitted, DEF USR0 is 
assumed. 

offset 

Is an integer expression from 0 to 65535. It 
specifies the starting address of the subroutine as 
an offset into the current segment. 


The current segment is as defined by the most 
recently executed DEF SEG statement or, if no DEF 
SEG statement has been executed, is the GW- 
BASIC Data Segment. 


Characteristics 

Any number of DEF USR statements may appear in a program to 
redefine subroutine starting addresses, thus allowing access to as 
many subroutines as necessary. To obtain the starting address of a 
subroutine, GW-BASIC adds the value of offset to the start address 
of the current segment. 


Example 

100 DEF SEG = 0 

200 DEF USR0 = 24000 
210 X = USR0(Y a 2/2.89) 














- DEFINT/SNG/DBL/STR Statements 

Declare the variable type in accordance with the letter(s) specified . 
These statements are usually used in a program. 

DEFfype letter[ - letter][ , letter[ - letter]]... 

Where 


SYNTAX ELEMENT 

MEANING 

type 

Is INT, SNG, DBL, or STR. No space should be 
entered between DEF and INT, SNG, DBL, or STR. 

letter 

Represents a letter from the alphabet (A-Z) 

Characteristics 



Any variable names beginning with the letter(s) specified in the range 
of letters will be considered. The type of variable specified by the 
type declaration character (%,!,#,$) always takes precedence over 
a DEF type statement. 


If no type declaration statements are encountered, GW-BASIC 
assumes all variables without declaration characters are single preci¬ 
sion variables. DEFfype statements must precede the use of the defin¬ 
ed variables. 
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Examples 

10 DEFDBL L-P 

All variables beginning with the letters L, M, N, O, and P will be dou¬ 
ble precision variables. 

10 DEFSTR A 

All variables beginning with the letter A will be string variables. 

10 DEFINT l-N, W-Z 

All variable beginning with the letters I, J, K, L, M, N, W, X, Y, Z will 
be integer variables. 


DELETE Command 


Erases program lines. (DELETE is usually used in immediate mode.) 


DELETE [Iinenum1][ - 

[Iinenum2]] 

Where 

SYNTAX ELEMENT 

MEANING 

linenum 1 

Is the first line to be erased 

Unenum2 

Is the last line to be erased 























Characteristics 


GW-BASIC always returns to command level after a DELETE is ex¬ 
ecuted. If either linenuml or Iinenum2 does not exist, an’’Il¬ 
legal function call” error occurs. A period (.) can be used instead of 
the line number to indicate the current line. 


Examples 


DELETE 80 
DELETE 80-120 
DELETE -80 
DELETE 80- 


Deletes line 80. 

Deletes lines 80 through 120, inclusive. 

Deletes all lines up to and including line 80. 

Deletes all lines from line 80 through the end of 
the program. 


DIM Statement 


Specifies the array name, the number of dimensions and the subscript 
upper bound per dimension. The DIM statement may specify one or 
more arrays. DIM is usually used in a program. 


DIM array ( list-of-subscripts )[, array ( list-of-subscripts ) 
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Where 


SYNTAX ELEMENT 

MEANING 

array 

Is a valid array name. Any legal variable name may 
be used. 

list-of-subscripts 

Comprises one or more numeric expressions which 
specify the array dimensions. Each subscript must 
be separated from the next by a comma. The 
number of subscripts specifies the number of 
dimensions, and the value of each specifies the 
subscript upper bound. 

Characteristics 


If an array name is used without a corresponding DIM statement, the 
maximum value of the array’s subscript(s) defaults to 10. If a subscript 
is used that is greater than the maximum specified, a ’’Subscript out 
of range” error occurs. The minimum value for a subscript is always 
0, unless otherwise specified with the OPTION BASE statement. 

If no DIM is specified, the first reference to an array element in the 
program will create the array with the specified number of dimensions. 
For example, if a program statement refers to: 

AR1(3,5,10) 


Then AR1 is created with 3 dimensions and a default upper bound 
of 10 for each dimension. 

The DIM statement sets all numeric array elements to an initial value 
of zero and elements of string arrays to null strings. 












Theoretically, the maximum number of dimensions allowed in a DIM 
statement is 255 and the maximum number of elements per dimen¬ 
sion is 32767. In reality, however, these numbers are limited by line 
length and memory size. 

If you try to redimension an array without first erasing it, a "Duplicate 
Definition" error occurs. You must first use the ERASE statement to 
erase an array before redimensioning it. 


Number of Elements per Dimension 


IF... 


AND IF... 



no DIM is used 


OPTION BASE 0 
is set 


11 elements (subscripts 
0-10 are allowed in each 
dimension). 


OPTION BASE 1 
is set 


10 elements (subscripts 
1-10 are allowed in each 
dimension). 


DIM is used 


OPTION BASE 0 
is set 


the number of elements 
in each dimension is 
calculated by adding 1 to 
each upper bound 
subscript. 


OPTION BASE 1 
is set 


the number of elements 
in each dimension coin¬ 
cides with each upper 
bound subscript. 


8-92 


GW-BASIC INTERPRETER USER GUIDE 


















COMMANDS, STATEMENTS AND FUNCTIONS 


To Define an Array 


YOU MUST... 

AND EITHER... 

OR... 

establish the subscript 
lower bound 

use an OPTION BASE 

1 statement 

adopt the default . 
OPTION BASE 0. 

assign a name to the 
array 

use a DIM statement 

refer to an array element 
within the program. 

establish the number 
of dimensions 

use a DIM statement 

refer to an array element 
within the program. 

establish the subscript 
upper bound per 
dimension 

use a DIM statement 

refer to an array element 
within the program. Note: 
In this case a subscript 
upper bound of 10 for 
each dimension is 
assumed. 



Remarks 

A DIM statement does not set subscript upper bounds if the statement 
is jumped over (see last example). 


Example 


10 DIM A(5),B$(20,30,15) 


MKM 


8-93 













Example 


10 INPUT 1 
20 DIM ARRAYI(I) 

30 FOR K = 0 TO I 
40 READ ARRAYI(K) 
50 NEXT 


Example 

10 DIM A(20) 

20 FOR I = 0 TO 20 
30 READ A(l) 

40 NEXT I 


Example 

LIST 

10 1 = 1 
20 GOTO 40 
30 DIM A(50) 

40 A(10) = 3 
50 A(11) = 45 
Ok 
RUN 

Subscript out of range in 50 
Ok 


The system displays: 

Subscript out of range in 50 

when statement 50 is executed, as statement 30 is jumped over and 
an upper bound of 10 is assumed by default. 
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DRAW Statement 


Draws an object as specified by the contents of a string expression. 
(Graphics Mode only) 


DRAW stringexp 


Where 


SYNTAX ELEMENT 

MEANING 

stringexp 

Is a string expression defining the sequence of 
Graphics Macro Language (GML) commands that 
will draw the object. 

Characteristics 


The DRAW statement makes a group of graphics statements available 
which facilitate the drawing of complex figures. A GML command is 
represented by a single character (i.e. U, D, L, R, E, F, G, H, M, B, 
N, A, C, S, X, P) or a pair of characters (TA) within the string stringexp, 
followed by one or two integer values that represent the coordinates 
of a point (in pixels). 

A WINDOW instruction does not have any effect on the DRAW state¬ 
ment, since DRAW draws directly in the viewport in screen coordinates. 



















Movement Commands 


Each of the following movement commands begin movement from the 
current graphics position. This is usually the coordinate of the last 
graphics point plotted with another GML command, LINE, or PSET. 
The current position defaults to the center of the screen when a pro¬ 
gram is RUN. 

The GML movement commands specify movements by an integer 
( n ), or by a pair of integers ( x , y ) in the M command. The actual 
distance travelled (in pixels) is given by this integer multiplied by the 
“scale factor”, defined via the S command (see below). 


COMMAND 

ACTION 


U [n] 

Move up. The number of points moved is n 
factor (set by the S command below). If n i 
ted 1 is supplied. 

* scale 
s omit- 

D [n] 

Move down. The number of points moved 
scale factor (set by the S command below) 
omitted 1 is supplied. 

Ms n * 
i. If n is 

L[n] 

Move left. The number of points moved is n 
factor (set by the S command below). If n i 
ted 1 is supplied. 

* scale 
is omit- 

R[n] 

Move right . The number of points movec 
scale factor (set by the S command below) 
omitted 1 is supplied. 

Ms n * 

1. If n is 

E[n] 

Move diagonally up and right. The number of points 
moved is n * scale factor (set by the S command 
below). If n is omitted 1 is supplied. 
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COMMAND 

ACTION 

F[n] 

Move diagonally down and right. The number of 
points moved is n * scale factor (set by the S com¬ 
mand below). If n is omitted 1 is supplied. 

G [n] 

Move diagonally down and left.The number of 
points moved is n * scale factor (set by the S com¬ 
mand below). If n is omitted 1 is supplied. 

H [n] 

Move diagonally up and left. The number of points 
moved is n * scale factor (set by the S command 
below). If n is omitted 1 is supplied. 

M x,y 

Move absolute or relative. If x is preceded by a plus 
(+) or minus (-), x and y are added to the current 
graphics position, (move relative). Otherwise, they 
are absolute coordinates with respect to the origin 
of the axes (move absolute). 

B 

Move without plotting any points. B may precede 
any of the above-mentioned movement commands. 

N 

Move but return to original position when finished. 
N may precede any of the above-mentioned move¬ 
ment commands. 














Further GML Commands 

• 

COMMAND 

ACTION 


A n 

Set angle n. n may range from 0 to 3, where 0 is 

0 degrees, 1 is 90, 2 is 180, and 3 is 270. 

TA n 

Rotate angle n. n is expressed in degrees in the 
range -360 to 360. If n is positive, rotation is 
counter-clockwise, if n is negative, rotation is 
clockwise. If n is outside the specified range, an 
’’Illegal function call” error occurs. 

C n 

Set color number n (from 0 to 3 in Medium Resolu- 
tion, and 0 to 1 in High or Super Resolution). 

Sk 

Set scale factor, k may range from 1 to 255. The 
scale factor is defined as /c/4. The scale factor, 
multipled by the distances given with 
U,D,L,R,E,F,G,H or relative M commands gives the 
actual distance travelled (in pixels). If the S com¬ 
mand is omitted, a scale factor of 1 (i.e. /c = 4) is 
assumed. 

X stringexp 

Execute substring. This powerful command allows 
you to execute a second substring from a string. 

You can have one string execute another, which 
executes a third and so on. Spaces are ignored in 
stringexp ; but can be inserted for legibility. 


W 
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COMMAND 

ACTION 

P n, m 

n is the color number chosen to paint the interior 
of the closed figure and m is the border color 
number. You must specify both parameters or an 
error will occur. Both parameters can range from 
0 to 3 in Medium Resolution and from 0 to 1 in High 
or Super Resolution mode. 


Remarks 

In all GML commands, numeric arguments can be constants like ”327” 
or =numvar; where numvar is the name of a numeric variable. 
The semicolon is necessary if you enter a variable this way or if you 
use the X command, otherwise you can omit the semicolon between 
commands. 

On the screen, the number of horizontal pixels differs from the number 
of vertical pixels. The spacing between the pixels also differs. 
Therefore, in order to draw lines of equal length along the x- and y- 
axes, you must multiply the vertical points by the aspect ratio (a frac¬ 
tion that is used to take into account the difference in the horizontal 
and vertical lengths of the screen). For a standard monitor the aspect 
ratio is 4/3. You must bear in mind these considerations in order to 
maintain the horizontal and vertical proportions of lines in a figure. 

The following program draws a square in Medium Resolution: 


10 SCREEN 1 
20 A = 40 
30 B = 48 

40 DRAW ”U = A; R = B; D = A; L = B;” 







In Medium Resolution there are 320 horizontal pixels and 200 vertical 
pixels, therefore 16 horizontal points are equal in length to 10* 4/3 
vertical points, and, consequenty, a line of 48 horizontal points equals 
a line of 40 vertical points. 


Example 1 

10 U$ = ”U30;” : D$ = ”D30;” : L$ = ”L40;”: R$ = ”R40;” 

20 BOX$ = U$ + R$ + D$ + L$ 

30 DRAW ”XBOX$;” 

40 REM DRAW ”XU$;XR$;XD$;XL$;” would have drawn the same 
box 


Example 2 


10 DRAW ’’U50R50D50L50” ’Draw a box 
20 DRAW ”BE10” ’Move up and right into box 


30 DRAW ”P1,3” ’Paint interior 


Example 3 

10 FOR D = 0 TO 360 ’Draw some spokes 
20 DRAW ”TA = D;NU50” 

30 NEXT D 
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EDIT Command 


Lets you change a program line. EDIT is only used in immediate mode. 


EDIT [linenum \ . J 


Where 


SYNTAX ELEMENT 

MEANING 

linenum 

Is a program line number. If no such line exists, 
an ’’Undefined line number” error message is 
displayed. 

• 

Alternatively a period can be used instead of a line 
number to specify the current line. 


Characteristics 

When you enter an EDIT command, GW-BASIC displays the specified 
line and positions the cursor under the first digit of the line number. 
The line may then be modified by using the special editor keys. 

The EDIT command can be used to redisplay and edit a line which 
has just been entered. (The line number symbol can be specified 
in this case). 

















You can also use the LIST command to display a group of program 
lines for editing. 


For examples see Chapter 2. 


END Statement 


Terminates program execution, closes all open data files, and returns 
to command level. END is only used in a program. 


END 


Characteristics 


END statements may be placed anywhere in the program to terminate 
execution. Unlike the STOP statement, END does not cause a ’’Break 
in line nnnnn” message to be printed. An END statement at the end 
of a program is optional. GW-BASIC always returns to command level 
after an END is executed. 


Example 

520 IF K> 1000 THEN END ELSE GOTO 20 
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ENVIRON Statement 


Allows modification of parameters in GW-BASIC’s Environment Strinq 
Table. 


ENVIRON parm 


Where 


SYNTAX ELEMENT 

MEANING 

parm 

Is a valid string expression containing the new En¬ 
vironment String parameter. 


The string expression must only include uppercase 
letters. 

Characteristics 


The ENVIRON statement may be used, for example, to change the 
’’PATH” parameter for a child process. Parameters may also be pass¬ 
ed to a child process by inventing a new environment parameter. 















Remarks 


1. parm must be of the form parm-id= text where: 

a. parm-id is the name of the parameter such as ’’PATH”. 

b. parm-id must be separated from text by ’ = ’ or ’ ’ (blank) such 
as ’’PATH = ENVIRON takes everything to the left of the first 
blank or ” = ” as the parm-id, and everything to the right 
as text. 


c. text is the new parameter text. If text is a null string, or con¬ 
sists only of (a single semi-colon, such as ’’PATH =;”) then 
the parameter (including parm-id =) is removed from the En¬ 
vironment String Table and the Table is compressed. 


2. If parm-id does not exist in the Environment String Table, then 
parm-id is added at the end of the Environment String Table. 


3. 


If parm-id does exist, it is deleted, the Environment String Table 
is compressed and the new parm-id is added at the end. 


Examples 

The following MS-DOS command will create a default ’’PATH” to the 
Root Directory on disk A: 


PATH = A: 

The PATH may be changed in GW-BASIC to a new value by: 

ENVIRON ’’PATH = A:SALES;A:ACCOUNTS” 

A new parameter may be added to the Environment String Table: 


ENVIRON ’’SESAME = PLAN 


» » 



mmmm 
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The Environment String Table now contains: 

PATH = A:SALES; A: ACCOUNTS 
SESAME = PLAN 

If you then entered: 

ENVIRON ’’SESAME = ;” 


then you would have deleted SESAME, and you would have a table 
containing: 

PATH = A:SALES; A: ACCOUNTS 


Possible errors 

’’Type mismatch”: if parm is not a string. 

’’Out of Memory”: if the Environment Table is full and no more can 
be allocated. 


ENVIRONS Function 


Allows you to retrieve the specified Environment String from GW- 
BASIC’s Environment String Table. 


ENVIRONS {(parm )|( nth-parm ) j 
















Where 


SYNTAX ELEMENT 

MEANING 

parm 

Is a string expression containing the parameter to 
be retrieved. 


The string expression must only include uppercase 
letters. 

nth-parm 

Is an integer expression returning a value in the 
range 1 to 255. 

Remarks 


1. If a string argument is used, ENVIRONS returns a string contain¬ 
ing the text following parm= from the Environment String Table. 

2. If parm = is not found, or no text follows parm = then a null string 
is returned. 

3. If a numeric argument is used, ENVIRONS returns a string con¬ 
taining the nth-parm from the Environment String Table including 
the parm. 

4. If there is no nth-parm then a null string is returned. 

Possible errors 

’’Illegal function call”: if nth-parm is out of range. 

’’Type mismatch”: if parm is not a string. 

’’String too long”: if the string is longer than 255 characters. 
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EOF Function 


Indicates whether the end of a file has been reached. EOF is usually 
used in a program. 


EOF ( filenum) 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the file number specified in the OPEN statement 

Characteristics 


Returns-1 (true) if the end of a sequential file has been reached. Use 
EOF to test for end-of-file while inputting, to avoid ’’Input past end” 
errors. 

When EOF is used with random access files, it returns ’’true” if the 
last executed GET statement was unable to read an entire record 
because of an attempt to read beySnd the end. 

When EOF is used with a communications device, the definition of the 
end-of-file condition is dependent on the mode (ASCII or binary) in 
which the device was opened. In binary mode, EOF is true when the 
input queue is empty (LOC(n)= 0). It becomes false when the input 
queue is not empty. In ASCII mode, EOF is false until a CTRL Z is 
received, and from then on it will remain true until the device is closed. 
















Example 

5 DIM M(500) 

10 OPEN ”l”,1 ,”DATA” 
20 K = 0 

30 IF EOF(1) THEN 100 
40 INPUT #1, M(K) 

50 K = K + 1:GOTO 30 


This example reads data from the sequential file named ’’DATA”. 
Values are read into array M until the end of file is reached. 


ERASE Statement 


Releases space and variable names previously reserved for arrays. 
The data is lost and the array(s) no longer exist. 


ERASE array [ , array]... 




Where 


SYNTAX ELEMENT 


MEANING 


array 


Is the name of an array to be erased. 
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Characteristics 

Arrays may be re-dimensioned after they are ERASEd, or the previously 
allocated array space in memory may be used for other purposes. If 
an attempt is made to redimension an array without first ERASEing 
it, a ’’Duplicate Definition” error occurs. 

It is not good programming practice to reuse an indentifier. This may 
generate errors or reduce the program readability. You may, however, 
find it useful to redeclare an erased array; for example, when an array 
name is known by a subroutine and you want to pass arrays with dif¬ 
ferent number of dimensions of subscript upper bounds to this 
subroutine. 

Example 

10 DIM A(15,15),B(10,20) 


100 ERASE A,B 

110 DIM A (100),B(2,2,2) 

Upon execution of statement 100, arrays A and B are deleted and the 
corresponding memory space is made free. You may define other ar¬ 
rays (see statement 110) with the same names but different numbers 
of dimensions and upper bounds. 


ERDEV and ERDEV$ Functions 


ERDEV is an integer function which contains the error code returned 
by the last device to declare an error. 

ERDEV$ is a string function which contains the name of the device 
driver which generated the error. 






i ERDEV | ERDEV$J 


Characteristics 

ERDEV is set by the Interrupt X’24’ handler, when an error within MS- 
DOS is detected. ERDEV will contain the INT 24 error code in the lower 
8 bits, and the upper 8 bits will contain the ’’Word attribute bits” 
(b15-b13) from the Device header block. 

If the error was on a character device, ERDEV$ will contain the 8-byte 
character device name. If the error was not on a character device, 
ERDEV$ will contain the two character block device name (A:, B:, C: 
etc). 

Remarks 

For the sake of compatibility between different releases, it is advisable 
to perform error checking by using ERDEV rather than ERDEV$. 


Example 

If a user installed device driver ’’MYLPT2” caused a ’’Out of Paper” 
error via INT 24, and the driver’s error number for that problem was 
9, ERDEV will contain the error number 9 in the lower 8 bits and the 
device header word attributes in the upper 8 bits, and ERDEV$ will 
contain ’’MYLPT2”. 
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ERR and ERL Functions 


The ERR function returns the error code and the ERL function returns 
the number of the line which contains the error. 


{ERR | ERL j 


Characteristics 

When an error handling routine is entered, the function ERR contains 
the error code and the function ERL contains the line number of the 
line in which the error was detected. 

The ERR and ERL functions are usually used in IF...THEN statements 
to direct program flow in the error handling routine. 

If the statement that caused the error was a direct mode statement, 
ERL will contain 65535. 

If the line number is not on the right side of the relational operator, 
it cannot be renumbered with RENUM. Because ERL and ERR are 
reserved functions, neither may appear to the left of the equal sign 
in a LET (assignment) statement. 

GW-BASIC error codes are listed in Appendix A. 

To test whether an error occurred in a direct statement, use: 

IF 65535 = ERL THEN .... 

Otherwise, use: 

IF ERR = error-code THEN ... 


IF ERL = linenum THEN ... 
















Example 

LIST 

10 REM RECTANGLE2 

20 ON ERROR GOTO 70 

30 INPUT ’’Length and Width”;L,W 

40 IF (L< 0) OR (W<0) THEN ERROR 200 

50 PRINT ”Area = ”;L*W;” L = ”;L;” W = ”;W 

60 GOTO 30 

70 IF (ERR = 200) AND (ERL = 40) 

THEN PRINT ”L or W<0”:RESUME 30 
80 ON ERROR GOTO 0 
90 END 
Ok 
RUN 

Length and Width? -2,5 
L or W<0 

Length and Width? 2,5 
Area= 10 L= 2 W= 5 
Length and Width? a C 
Break in 30 
Ok 

If you enter a negative value for L or W, the error handling routine is 
activated and the system displays: 

L or W <0 

Execution is resumed at statement 30 (see RESUME statement below). 
Note the use of ERR and ERL functions in the error handling routine. 
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ERROR Statement 


Simulates the occurrence of a GW-BASIC error, or generates a user 
defined error. 


ERROR n 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression representing an error code. 
It must be greater than 0 and less than or equal 
to 255. If it is not an integer, it is rounded to the 
nearest integer. 














Characteristics 


IF... 

THEN... 

the value of n equals 
an error code already 
in use by GW-BASIC 

the ERROR is simulated, and the corresponding 
error message will be displayed. 

For example: 

LIST 

10 S=10 

20 T = 5 

30 ERROR S + T 

40 END 

Ok 

RUN 

String too long in line 30 

Ok 

Or, in immediate mode: 

ERROR 15 

String too long 

Ok 

the value of n is 
greater than any error 
codes used by 
GW-BASIC 

the ERROR statement will generate a user-defined 
error. This user-defined error code may then be 
handled in the error trapping routine (see the ON 
ERROR statement in this chapter). 

Note: To define your own. error, use a value that 
is greater than any used by GW-BASIC error codes. 

(It is preferable to use the highest available values, 
so compatibility may be maintained if more error 
codes are added to GW-BASIC). 
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IF... 

THEN... 

an ERROR statement 

GW-BASIC responds with the message: 

specifies a code for 


which no error 

Unprintable error 

message has been 


defined 



EXP Function 


Returns 


e (base of natural logarithms) to the power of the argument. 


EXP( numexp ) 


Remarks 

numexp must be < =87.3365. If EXP overflows, the ’’Overflow” er¬ 
ror message is displayed, machine infinity with the appropriate sign 
is supplied as the result, and execution continues. 

EXP is calculated in single precision, unless ID is supplied in the 
GWBASIC command line. 


Example 


10 X = 5 

20 PRINT EXP(X-I) 
RUN 
54.59815 
Ok 



8-115 
























- FIELD Slaleinenl 


Allocates space for variables in a random file buffer. FIELD is usually 
used in a program. 

FIELD [#] filenum , width AS stringvar [, width AS stringvar]... 

Where 

SYNTAX ELEMENT 

MEANING 

filenum 

Is the number under which the file was OPENed 

width 

Is the number of characters to be allocated to 
stringvar 

stringvar 

Is a string variable name that will be used for ran¬ 
dom file access 

Characteristics 


Before a GET statement or PUT statement can be executed, a FIELD 
statement must be executed to format the random file buffer. 

The total number of bytes allocated in a FIELD statement must not 
exceed the record length that was specified when the file was OPEN- 
ed. Otherwise, a ’’Field overflow” error occurs. (The default record 
length is 128 bytes.) 
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Any number of FIELD statements may be executed for the same file. 
All FIELD statements that have been executed will remain in effect 
at the same time. 


Remarks 

Do not use a FIELDed variable name in an input statement or to the 
left of the equal sign in an assignment statement. 

Once a variable name is FIELDed, it points to the correct place in the 
random file buffer. If a subsequent INPUT or LET statement with that 
variable name on the left side of the equal sign is executed, the variable 
no longer refers to the random file buffer, but to the variables stored 
in string space. 

Note that a variable name, previously defined in a FIELD statement, 
may be inserted to the right of the equal sign in an assignment state¬ 
ment. 


Example 1 


10 FIELD# 1,20 AS N$,10 AS ID$,40 AS ADD$ 


Allocates the first 20 positions (bytes) in the random file buffer to the 
string variable N$, the next 10 positions to ID$, and the next 40 posi¬ 
tions to ADD$. FIELD does NOT place any data in the random file 
buffer. 


Example 2 


10 

15 

20 

25 

30 

35 

40 

45 

50 


OPEN ”R”, #1 ,”A:PHONELST”,35 
FIELD #1,2 AS RECNBR$,33 AS DUMMY$ 
FIELD #1,25 AS NAMES,10 AS PHONENBR$ 
GET #1 

TOTAL = CVI(RECNBR$) 

FOR I = 2 TO TOTAL 
GET #1, I 

PRINT NAMES, PHONENBRS 
NEXT I 
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Illustrates a multiple defined FIELD statement. In statement 15, the 
35 byte field is defined for the first record to keep track of the number 
of records in the file; statement 20 defines the field for individual names 
and phone numbers. 


Example 3 

10 FOR LOOP°/o = 0 TO 7 

20 FIELD# 1,(LOOP%* 16) AS OFFSETS,16 AS A$(LOOP%) 

30 NEXT LOOP°/o 

Shows the construction of a FIELD statement using an array of 
elements of equal size. The result is equivalent to the single 
declaration: 

FIELD #1,16 AS A$(0),16 AS A$(1).16 AS A$(6),16 AS A$(7) 


Example 4 


10 DIM SIZE°/o(4°/o): REM ARRAY OF FIELD SIZES 
20 FOR LOOP% = 0 TO 4%:READ SIZEo/o (LOOP%): NEXT 
LOOP°/o 

30 DATA 9,10,12,21,41 


120 DIM A$(4%): REM ARRAY OF FIELDED VARIABLES 

130 OFFSET% = 0 

140 FOR LOOP% = 0 TO 4% 

150 FIELD # 1 ,OFFSET% AS OFFSETS,SIZE°/o(LOOP%) AS 
A$(LOOP°/o) 

160 OFFSET°/o = OFFSET% + SIZE%(LOOP%) 

170 NEXT LOOP% 

Creates a field in the same manner as Example 3. However, the ele¬ 
ment size varies with each element. The equivalent declaration is: 

FIELD # 1 ,SIZE%(0) AS A$(0),SIZE%(1) AS A$(1),... 

SIZE°/o(4°/o) AS A$(4°/o) 
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Example 5 

10 FIELD #1,225 AS TST$ 


Note that you must observe the maximum length restriction for various 
variables. For example in the FIELD statement above the maximum 
length of TST$ is 255. 


FILES Command 



Displays the names of files residing on the specified directory. 


FILES [filespec \ pathname] 



Where 


SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression specifying either a filename 
or a directory name, and optionally a drive. If the 
drive is omitted, the MS-DOS default drive is 
assumed. If no directory is specified, the current 
directory for the specified drive is assumed. If only 
FILES is specified, all the files on the current direc¬ 
tory of the MS-DOS default drive will be listed. 
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Characteristics 


A filename may contain question marks (?) or asterisks (*) used as 
wild cards. A question mark will match any single character in the 
filename or extension. An asterisk will match one or more characters 
starting at the position. The asterisk is a shorthand notation for a series 
of question marks. The asterisk need not be used in the case where 
all the files on a drive are requested, e.g., FILES ”B:”. 


Examples 

FILES 

Shows all files on the current directory 

FILES ”*.BAS” 

Shows all files with an extension of .BAS 

FILES 

Shows all files on drive A 
FILES ”A:” 

Equivalent to the preceding example 

FILES ”GEO?.BAS” 

Shows all files on the current directory of the MS-DOS default drive 
that have a filename of 4 characters beginning with GEO and an ex¬ 
tension of .BAS 

Sub-directories are denoted by < DIR > following the directory name. 

FILES ”\SALES” 

If SALES is a subdirectory of the current directory, this command 
displays SALES <DIR>. If SALES is a file in the current directory, 
this command displays SALES. 
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FILES ”\SALES\MARY” 

Displays MARY <DIR>if MARY is a subdirectory of SALES or, if 
MARY is a file, displays its name. 


FIX Function 


Returns the truncated integer part of the argument. 


FIX( numexp ) 


Characteristics 

FlX(numexp) is equivalent to SGN(ni/mexp)*INT(ABS(mjmexp)). The 
major difference between FIX and INT is that FIX does not return the 
next lower number for a negative argument. 


Examples 

PRINT FIX(58.75) 

58 

Ok 

PRINT FIX(-58.75) 

-58 

Ok 











FOR...NEXT Statements 


Allow a series of statements to be performed in a loop a specified 
number of times. FOR/NEXT are usually used in a program. 


FOR control-variable = initial-value TO final-value[ STEP increment] 


[loop statements] 


NEXT [control-variable][ , control-variable] ... 
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Where 

SYNTAX ELEMENT 

MEANING 

control-variable 

Is an integer or single-precision variable used as 
a counter 

initial-value 

Is a numeric expression specifying the first value 
assigned to the control-variable 

final-value 

Is a numeric expression specifying the limit of the 
control-variable 

increment 

Is a numeric expression specifying the value to be 
added (with its algebraic sign) to the control- 
variable when the NEXT statement is encountered 


Characteristics 


The program lines following the FOR statement are executed until the 
NEXT statement is encountered. Then the control-variable is ad¬ 
justed by the amount specified by increment . A check is perform¬ 
ed to see if the value of the control-variable is now greater than 
the final-value . If it is not greater, the program branches back to 
the statement after the FOR statement and the process is repeated. 
If it is greater, execution continues with the statement following the 
NEXT statement. This is a FOR...NEXT loop. 


If STEP is not specified, the increment is assumed to be one. If 
increment is negative, the final-value must be less than the 
initial-value . The control-variable is decreased each time through 
the loop. The loop is executed until the control-variable is less than 
the final-value 


8-123 














The control-variable must be an integer or single precision numeric 
variable. If a double precision numeric variable is used, a ’’Type 
mismatch” error will result. 

The body of the loop is skipped if either: 

• the increment is positive, and the initial-value exceeds the 
final-value 

• the increment is negative, and the initial-value is less than 
the final-value 


Nested Loops 

FOR...NEXT loops may be nested; that is, a FOR...NEXT loop may 
be placed within the context of another FOR...NEXT loop. When loops 
are nested, each loop must have a unique variable name as its counter. 
The NEXT statement for the inside loop must appear before that for 
the outside loop. If nested loops have the same end point, a single 
NEXT statement (with a list of control variables) may be used for all 
of them. 


Note that a statement of this form: 

NEXT VI, V2, V3 

performs the same action as the sequence of statements: 

NEXT VI 
NEXT V2 
NEXT V3 


The variable(s) in the NEXT statement may be omitted, in which case 
the NEXT statement will match the most recent FOR statement. When 
using nested loops, the variable(s) in each NEXT statement must be 
specified. 


If a NEXT statement is encountered before its corresponding FOR 
statement, a ’’NEXT without FOR” error message is issued and ex¬ 
ecution is terminated. 
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Delay Loops 

Between two statements, in a program, you can insert a dummy 
FOR/NEXT loop (i.e. without statements between FOR and NEXT) in 
order to delay the execution of the second statement. This can prove 
useful in various situations, for example in animation. 


Example 1 

10 K = 10 

20 FOR 1 = 1 TO K STEP 2 
30 PRINT I; 

40 K = K+ 10 
50 PRINT K 
60 NEXT 
RUN 
1 20 
3 30 
5 40 
7 50 
9 60 
Ok 


Note that althrough the value of K is changed within the loop, the final- 
value remains as 10. 


Example 2 


10 J = 0 

20 FOR 1 = 1 TO J 
30 PRINT I 
40 NEXT I 

RUN 

Ok 


In this example, the loop does not execute because the initial-value 
of the loop exceeds the final-value. 





Example 3 


10 1 = 5 

20 FOR 1 = 1 TO I + 5 
30 PRINT I; 

40 NEXT 

RUN 

1 23456789 10 
Ok 

In this example, the loop executes ten times. The final value for the 
loop variable is always set before the initial value is set. 


FRE Function 


Returns the number of bytes in memory not being used by GW-BASIC. 


FRE( dummy) 


Characteristics 

The argument to FRE is a dummy argument. Any value may be sup¬ 
plied. FRE(””) forces a garbage collection before returning the number 
of free bytes. 

GW-BASIC will not initiate garbage collection until all free memory has 
been used up. Therefore, using FRE(””) periodically will result in 
shorter delays for each garbage collection. 


Example 


PRINT FRE(0) 

14542 

Ok 
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GET (COM files) Statement 


Reads a specified number of bytes from the communications buffer. 
GET(COM files) is usually used in a program. 


GET [#] filenum , length 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is an integer expression returning a file number. 

length 

Is an integer expression returning the number of 
bytes to be transferred into the communications 
• buffer, length cannot be greater than the value 
specified by the LEN clause in the OPEN COM 
statement. 

Example 


100 GET# 2,80 
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GET (Files) Statement 


Reads a record from a random disk file into a random buffer. 
GET (Files) is usually used in program. 


GET [ # ] filenum[ , recordnum] 


Where 



SYNTAX ELEMENT 


MEANING 


filenum 


Is the number under which the file was OPENed 


Is the number of the record to be read, in the range 
1 to 16,777,215. If it is omitted, the next record 
(after the last GET) is read into the buffer. 


recordnum 


Characteristics 

The largest possible record number is 16,777,215. This permits large 
files with short record lengths. 

After a GET statement has been executed, you can either refer to 
FIELDed variables or use INPUT # or LINE # to read characters 
from the random file buffer. The EOF function may be used after a 
GET statement to see if that GET was beyond the end of file marker. 
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Example 

LIST 

10 OPEN ”r”,1,”A:RAND”,48 
20 FIELD 1,20 AS R1$,20 AS R2$,8 AS R3$ 
30 FOR L = 1 TO 4 
40 GET 1,L 

50 PRINT R1$,R2$,R3$ 

60 NEXT 
70 CLOSE 1 
80 END 
Ok 
RUN 

superman USA 11234621 

robin hood England 23462101 


Ok 

This program retrieves information stored in the specified file. The data 
read into the buffer may be accessed by the program. This is done 
here by a PRINT statement (statement 50). See the PUT (files) 
statement. 


GET (Graphics) Statement- 


Transfers to an array a graphic image contained within a rectangular 
area of the screen. 


GET [ STEP ] ( xl , yl ) - [ STEP ] ( x2 , y2 ), array 














Where 


SYNTAX ELEMENT 


MEANING 


(xl t y1)-(x2,y2) 


Define a rectangular area on the display screen. 
x1,y1 are the upper left and x2,y2 the lower right 
coordinates. They may be given in absolute or 
relative form (if the STEP option is used). 


array 


Is the name assigned to the array that will hold the 
image, bounded by the specified rectangle. 



Characteristics 

The GET statement transfers the screen image bounded by the rec¬ 
tangle described by the specified points into the array. The images 
can be transfered back to any position on the screen using the PUT 
statement. GET and PUT permit animation and high-speed object 
motion. 


The array must be numeric, but may be any precision. It must be dimen¬ 
sioned large enough to hold the entire image. It is advisable to use 
arrays of integer type; other types of array can return meaningless 
values after a GET statement is executed. 


Array Dimensions 

The storage format in the array is as follows: 

2 bytes containing the x dimension of the rectangular area (in pixels) 
2 bytes containing the y dimension of rectangular area (in pixels) 
The array data itself 
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Each line of pixels within the rectangular area, starting from the top 
line, is scanned from the left-hand margin; the color numbers for 8 con¬ 
secutive pixels are stored in the array at intervals. If there are less than 
a multiple of 8 pixels in a line being stored, the array element correspon¬ 
ding to the last pixels of the line, will be padded out with zeros. The 
required array size, in bytes, is: 


4 +INT(( x * bitsperpixel + 7 ) 18 )* y 


Where 

bitsperpixel is 2 in Medium Resolution, and 1 in High and Super 
Resolution. 

The bytes per element of an array type are: 

2 for integer 
4 for single precision 
8 for double precision 


Example 

For example if you want to GET a 10 by 12 image into an integer ar¬ 
ray, in Medium Resolution mode, the number of bytes required is 
4 +INT ((10*2 + 7)/8)*12 or 40 bytes. So, you would need an integer 
array with at least 20 elements. 

It is possible to examine the x and y dimensions and even the 
data itself if an integer array is used. The x dimension is in ele¬ 
ment 0 of the array, and the y dimension is found in element 1. 
It must be remembered, however, that integers are stored low byte 
first, then high byte, but the data is transferred high byte first (leftmost) 
and then low byte. 







Example 


10 CLS : SCREEN 3 : PSET(20,20) 

20 X$ = ’’R20D20L20U20” : DRAW X$ 

30 DIM BOX%(64) : GET(20,20)-(40,40),BOX% 
35 PRINT ’’PRESS A KEY” : A$ = INPUT$(1) 
40 CLS : PUT(100,100),BOX°/o 


GOSUB...RETURN Statements 


GOSUB transfers control to a GW-BASIC subroutine by branching to 
the specified line. RETURN transfers control to the statement follow¬ 
ing the most recent GOSUB (or ON...GOSUB) executed, or to a 
specified line. GOSUB/RETURN are only used in a program. 


GOSUB linenuml 

RETURN [Iinenum2] 


Where 


SYNTAX ELEMENT 

MEANING 

linenuml 

Is the first line number of the subroutine 

Hnenum2 

Is any line of your program different from linenuml 
and from the line number of the GOSUB statement 
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Characteristics 

A subroutine may be called any number of times in a program. A 
subroutine may also be called from within another subroutine. Such 
nesting of subroutines is limited only by available memory. 

The RETURN statement(s) in a subroutine causes GW-BASIC to 
branch back to the statement following the most recent GOSUB or 
ON...GOSUB statement executed. A subroutine may contain more than 
one RETURN statement, should logic dictate a return at different points 
in the subroutine. 

The Iinenum2 option may be included in the RETURN statement 
to return to a specific line number from the subroutine. Use this type 
of return with care, however, because any other GOSUBs, WHILES, 
or FORs that were active at the time of the GOSUB will remain active, 
and errors such as ’’FOR without NEXT” may result. 

Subroutines may appear anywhere in the program, but it is recom¬ 
mended that the subroutine be readily distinguishable from the main 
program. To prevent inadvertent entry into the subroutine, precede 
it with a STOP, END, or GOTO statement that directs program control 
around the subroutine. 

If either linenuml or Iinenum2 does not exist in the program, 
an ’’Undefined line number” error is returned. 


Example 

10 GOSUB 40 

20 PRINT ’’BACK FROM SUBROUTINE” 
30 END 

40 PRINT ’’SUBROUTINE”; 

50 PRINT ” IN”; 

60 PRINT ” PROGRESS” 

70 RETURN 

RUN 

SUBROUTINE IN PROGRESS 
BACK FROM SUBROUTINE 
Ok 





GOTO Statement 


Transfers control to a specified program line. 


GOTO linenum 


Where 


SYNTAX ELEMENT 

MEANING 

linenum 

Is the number of a line in the program 

Characteristics 



If linenum is the line number of an executable statement, that state¬ 
ment and those following are executed. If it is the line number of a 
nonexecutable statement, execution proceeds at the first executable 
statement encountered after linenum . If the specified 
linenum does not exist in the program, an ’’Undefined line number” 
error is returned. 
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Example 

LIST 

10 READ R 
20 PRINT ”R = ”;R, 

30 A = 3.14*R A 2 

40 PRINT ’’AREA =”;A 

50 GOTO 10 

60 DATA 5,7,12 

Ok 

RUN 

R = 5 AREA = 78.5 

R = 7 AREA = 153.86 

R = 12 AREA = 452.16 

?Out of DATA in 10 
Ok 


GWBASIC Command 


Initializes GW-BASIC and the operating environment (GWBASIC is an 
MS-DOS command, not a GW-BASIC command). 


GWBASIC [filespec \ pathname] [ <sfd/'n][[ >]> stdout ] 
[ /F: number-of-files] [ /S: I reel] [ /C: buffer-size ] 

[ /M: highest-memory ] [ , max-blocksize ]] [ /D ] 


Where 

Options beginning with a slash (/) are called switches. A switch is a 
means used to specify parameters. 














SYNTAX ELEMENT 


MEANING 


filespec (or 
pathname) 


Is a string literal (not included in quotation marks) 
that specifies a GW-BASIC program file. If the file 
is present, GW-BASIC proceeds as if a RUN 
filespec command were given after initialization is 
complete. 


A default extension of .BAS is used if none is sup¬ 
plied and the filename is less than 9 characters 
long. The filespec option allows GW-BASIC pro¬ 
grams to be run in batch by putting this form of the 
command line in an AUTOEXEC.BAT file. GW- 
BASIC programs which run this way will need to 
exit via the SYSTEM command in order to allow 
the next command from the AUTOEXEC.BAT file 
to be executed. 


stdin 


Is a literal string (not included in quotation marks) 
for the standard input file specification. GW-BASIC 
input is redirected from the file specified by stdin. 
When present, this parameter must appear before 
any switches. (See ”Re-direction of Standard In¬ 
put and Output below). 


stdout Is a literal string (not included in quotation marks) 

for the standard output file specification. GW- 
BASIC is redirected to the file specified by stdout. 
When present, this parameter must appear before 
any switches. (See ’’Re-direction of Standard Out¬ 
put” below). 


/F: number-of-files Is a switch that sets the maximum number of files 

(from 1 to 15) that may be open simultaneously dur¬ 
ing the execution of a GW-BASIC program. 
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SYNTAX ELEMENT 

MEANING 

If this switch is present, then the maximum number 
of files is set to number-of-files. Each file requires 

62 bytes for the File Control Block (FCB) plus 128 
bytes for the data buffer. The data buffer size may 
be altered via the /S: switch. If the /F: option is omit¬ 
ted, the number-of-files is set to 3. 

The number of open files that MS-DOS supports 
depends upon the value of the FILES = parameter 
in the CONFIG.SYS file. It is recommended that 
FILES = 10 for GW-BASIC. Remember that the first 

3 are taken by stdin, stdout, stderr, stdaux, and 
stdprn. One additional file handler is needed by 
GW-BASIC for LOAD, SAVE, CHAIN, NAME and 
MERGE. This leaves 6 for GW-BASIC File I/O, thus 
/F:6 is the maximum supported by MS-DOS when 
FILES = 10 appears in the CONFIG.SYS file. 

Attempting to OPEN a file after all the file handlers 
have been exhausted will result in a ’’Too many 
files” error. 

/S: Irecl 

Is a switch that sets the maximum record length 
allowed with random files. If this switch is present, 
then the maximum record length is set to Irecl. The 
record length option (record-length) on the OPEN 
statement cannot exceed this value. If the /S: op¬ 
tion is omitted, the record length defaults to 128 
bytes. The maximum value permitted for Irecl is 
32767 bytes. 











SYNTAX ELEMENT 


MEANING 


/C: buffer-size 


/M: [highest-memory] 
[,max-blocksize] 


If present, controls RS232 Communications. /C:0 
disables RS232 support; any subsequent I/O at¬ 
tempts will result in a ’’Device Unavailable” error. 
Specifying /C:n allocates n bytes for the receive 
buffer for each RS232 port present. If the /C: op¬ 
tion is omitted, GW-BASIC allocates 256 bytes for 
the receive buffer of each RS232 port present. 128 
bytes are always allocated to the transmit buffer. 
The maximum value permitted for buffer-size is 
32767. 


When present, highest-memory sets the maximum 
number of bytes that will be used as GW-BASIC 
workspace. GW-BASIC will attempt to allocate 64K 
of memory for the data and stack segment. If 
machine language subroutines are to be used with 
GW-BASIC programs, use the /M: switch to set the 
highest memory location that GW-BASIC can use. 
When omitted or 0, GW-BASIC attempts to allocate 
all it can up to a maximum of 65536 bytes. 

In order to load programs above the GW-BASIC 
workspace you must use the optional parameter 
max- blocksize to reserve areas for the workspace 
and your programs. This is necessary if you intend 
to use the SHELL command. Failure to do so will 
result in COMMAND being loaded on top of your 
routines when a SHELL command is executed. 

max-blocksize must be in Paragraphs (in multiples 
of 16). When omitted, &H1000 (4096) is assumed. 
This allocates 65536 bytes (65536 = 4096 x 16) for 
GW-BASIC’s Data and Stack segment. If you re¬ 
quire 65536 bytes for GW-BASIC and 512 bytes for 
machine language subroutines, then use 
/M:,&H1010 (4096 paragraphs for GW-BASIC + 
16 paragraphs for your routines). 


► 
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SYNTAX ELEMENT 

MEANING 

This option can also be used to shrink the GW- 
BASIC block in order to free more memory for 
SHELLing other programs. /M:,2048 says: 
’’Allocate and use 32768 bytes maximum for data 
and stack”. /M:32000,2048 allocates 32768 bytes 
maximum but GW-BASIC will only use the lower 
32000. This leaves 768 bytes available for program 
space. 

/D 

If present, causes the Double Precision 
Transcendental math package to remain resident. 
The functions that will be calculated in double preci¬ 
sion if this package is resident are: ATN, COS, 
EXP, LOG, SIN, SQR, and TAN. If omitted, this 
package is discarded and the space is freed for pro¬ 
gram use. The amount of memory required by this 
package is approximately 3,000 bytes. 











number-of-files, Irecl, buffer-size, highest-memory, and max-blocksize 
are numbers that may be Decimal, Octal (preceded by &0), or Hex¬ 
adecimal (preceded by &H). 


Examples 


A>GWBASIC PAYROLL 

Uses 64k of memory and 3 files, loads and executes PAYROLL.BAS. 

A>GWBASIC INVENT/F:6 

Uses 64k of memory and 6 files, loads and executes INVENT.BAS. 

A>GWBASIC /C:0/M:32768 


Disables RS232 support and uses only the first 32k of memory. 

A>GWBASIC /F:4/S:512 

Uses 4 files and allows a maximum record length of 512 bytes. 

A>GWBASIC TTY/C:512 


Uses 64k of memory and 3 files, allocates 512 bytes to 
buffers, load and execute TTY.BAS. 


RS232 receive 


Redirection of Standard Input and Output 

Under GW-BASIC you can redirect your Input and Output. Generally, 
standard input is read from the keyboard, but this can also be the con¬ 
tents of any file specified on the GW-BASIC command line. Standard 
output, generally to the screen, can be redirected to any device or file 
specified on the GW-BASIC command line. 


Remarks 


When redirected, all INPUT, LINE INPUT, INPUTS and INKEY$ 
statements will read from the file specified using stdin instead of 
from the keyboard. 
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2. All PRINT and PRINT USING statements will write to the file or 
peripheral device specified using stdout instead of the screen. 
If a pair of greater than symbols (> >) are entered before stdout, 
data output by PRINT or PRINT USING statements will be “ap¬ 
pended” to the specified file. 

3. Error messages go to standard output, and appear on the screen. 

4. File input from KYBD: still reads from the keyboard. 

5. File output to SCRN: still outputs to the screen. 

6. GW-BASIC will continue to trap keys from the keyboard when the 
ON KEY(n) statement is used. 

7. The printer echo key will not cause LPT 1: echoing if Standard Out¬ 
put has been re-directed. 

8. Typing CTRL BREAK will cause GW-BASIC to close any open 
files, issue the message’’Break in line line-number ” to stan¬ 
dard output, exit GW-BASIC, and return to MS-DOS. 

9. When input is re-directed, GW-BASIC will continue to read from 
this source until a CTRL Z is detected. This condition may be 
tested with the EOF function. If the file is not terminated by a 
CTRL Z or if an attempt is made to read past end-of-file by an 
INPUT # statement, then any open files are closed. The message 
’’Read past end” is then written to standard output, and GW- 
BASIC returns to MS-DOS. 

10. Because of the way in which MS-DOS handles text files it is not 
recommended to execute a program in GW-BASIC with output 
rerouted and appended to a file created previously, either with 
EDLIN or in sequential mode in GW-BASIC: commands such as 
TYPE will only be able to show you the original contents. 





Examples 

GWBASIC MYPROG > DATA.OUT 

Data read by INPUT and LINE INPUT will continue to come from the 
keyboard. Data output by PRINT goes into the file DATA.OUT. 

GWBASIC MYPROG < DATA-IN 

Data read by INPUT and LINE INPUT will come from DATA.IN. Data 
output by PRINT goes to the screen. 


GWBASIC MYPROG < MYINPUT.DAT >MYOUTPUT.DAT 

Data read by INPUT and LINE INPUT comes from the file MYIN¬ 
PUT.DAT and data output by PRINT goes into MYOUTPUT.DAT. 


GWBASIC MYPROG < \SALES\JOHN\TRANS. > > 
\SALES\SALES.DAT 

Data read by INPUT and LINE INPUT will now come from the file 
\SALES\JOHN\TRANS. Data output by PRINT will be appended to 
the file \SALES\SALES.DAT. 


HEX$ Function 


Returns a string which represents the hexadecimal value of the decimal 
argument. 


HEX$( numexp ) 


Characteristics 

The parameter numexp is rounded to an integer before HEX$ is 
evaluated. If numexp is negative, the two’s complement form is 
used. 
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Example 

10 INPUT X 
20 A$ = HEX$(X) 

30 PRINT X ’’DECIMAL IS ” A$ ” HEXADECIMAL” 

RUN 
? 32 

32 DECIMAL IS 20 HEXADECIMAL 
Ok 

See the OCT$ function later in this chapter for details on octal conver¬ 
sion. 


IF...GOTO....ELSE and IF...THEN...ELSE Statements 


Make a decision regarding program flow based on the result of a 
specified condition. IF...GOTO...ELSE and IF...THEN...ELSE are usual¬ 
ly used in a program. 

Syntax 1 


IF condition GOTO linenum [ ELSE [statements]linenum}] 


Syntax 2 


IF condition THEN [statements \linenum J[ ELSE 
[statements | linenum )] 













Where 

SYNTAX ELEMENT 

MEANING 

condition 

May be a numeric, relational, or logical expression. 
GW-BASIC determines whether the condition is 
true or false by testing the result of the expression 
for non-zero and zero respectively. A non-zero 
result is true and a zero result is false. Because 
of this, you can test whether the value of a variable 
is non-zero or zero by merely specifying the name 
of the variable as condition. 

statements 

Are one or more statements. Each statement must 
be separated from the preceding one by a colon (:). 

linenum 

Is a line number of the program in memory 

Characteristics 


If the result of condition is true (not zero), the GOTO or THEN 
clause is executed. GOTO is always followed by a line number. THEN 
may be followed by either a line number for branching or one or more 
statements to be executed. If the result of condition is false (zero), 
the GOTO or THEN clause is ignored and the ELSE clause, if pre¬ 
sent, is executed. Execution continues with the next executable state¬ 
ment. A comma is allowed before THEN. 
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Nesting of IF Statements 

IF...THEN...ELSE statements may be nested. Nesting is limited only 
by the length of the line. For example: 

IF X>Y THEN PRINT ’’GREATER” ELSE IF Y>X 
THEN PRINT ’’LESS THAN” ELSE PRINT ’’EQUAL” 

is a legal statement. If the statement does not contain the same number 
of ELSE and THEN clauses, each ELSE is matched with the closest 
unmatched THEN. For example: 

IF A = B THEN IF B = C THEN PRINT ”A = C” 

ELSE PRINT ”A< >C” 

will not print ”AoC” when AoB. 

If an IF...THEN statement is followed by a line number in direct mode, 
an ’’Undefined line” error results, unless a statement with the specified 
line number had previously been entered in indirect mode. 


Remarks 

When using IF to test equality for a value that is the result of a floating¬ 
point computation, remember that the internal representation of the 
value may not be exact. Therefore, the test should be against the range 
over which the accuracy of the value may vary. For example, to test 
a computed variable A against the value 1.0, use: 

IF ABS(A-1,0)< 1 .OE-6 THEN ... 

This test returns true if the value of A is 1.0 with a relative error of 
less than 1 .OE-6. 


Example 1 

200 IF I THEN GET# 1,1 

This statement GETs record number I, if I is not zero. 






Example 2 

100 IF(I < 20) * (I > 10)THEN DB = 1979-l:GOTO 300 
110 PRINT ’’OUT OF RANGE” 


In this example, a test determines if I is greater than 10 and less than 
20. If I is in this range, DB is calculated and execution branches to 
line 300. If I is not in this range, execution continues with line 110. 


Example 3 

210 IF IOFLAG THEN PRINT A$ ELSE LPRINT A$ 

This statement causes printed output to go either to the terminal or 
the line printer, depending on the value of the variable IOFLAG. If 
IOFLAG is zero, output goes to the line printer; otherwise, output goes 
to the screen. 


INKEY$ Function 


Returns either a one- or two-character string read from the keyboard 
or a null string if no character is pending at the keyboard. INKEY$ is 
always used in a program. 


INKEY$ 


Characteristics 

INKEY$ returns one of the following values: 

• A null string if no character is read from the keyboard 
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• A one-character string in accordance with a single character read 
from the keyboard 

• A two-character string if a Key (or a Key combination) is entered, 
that cannot be associated with a standard ASCII code. The first 
character is hex zero (00); the second indicates the extended code 
(refer to the ’’MS-DOS User Guide” for a list of the extended codes) 

Although more than one character may be pending in the keyboard 
buffer, a single character only will be read (unless it is part of an ex¬ 
tended code, in which case two characters are read). This value must 
then be assigned to a variable before it is considered by the GW-BASIC 
program. 

Remarks 


No characters are echoed by this statement. All characters are pass¬ 
ed to the program, except for the following control characters: 

PRTSC which prints the screen 

CTRL NUMLOCK which sets the system to pause 

CTRL BREAK which stops the program 

ALT CTRL DEL which resets the system 

Note that CR is passed to the program like any other character. 


Example 

1000 ’Timed input Subroutine 
1010 RESPONSES = ”” 

1020 FOR l% = 1 TO TIMELIMIT% 

1030 A$ = INKEY$:IF LEN(A$) = 0 THEN 1060 
1040 IF ASC(A$) = 13 THEN TIMEOUT% = 0:RETURN 
1050 RESPONSES = RESPONSES-)-A$ 

1060 NEXT 1% 

1070 TIMEOUT% = 1 :RETURN 








This subroutine returns two values: 


RESPONSES which contains the string entered from keyboard 


TIMEOUT% which equals 0 if the user enters a carriage return from 
the keyboard before a specified number of loops (TIMELIMIT%); 
otherwise TIMEOUT% equals 1. 


Example 

The following program will display the INKEY$ results. 


10 S$ = INKEY$ 

20 IF LEN(S$) = 0 THEN GO TO 10 
30 IF LEN(S$) = 2 THEN GO TO 100 
35 ’ ... DISPLAYS 1-BYTE CODES .... 

40 PRINT HEX$(ASC(S$)) 

50 GOTO 10 

100 ’ ... DISPLAYS 2-BYTE CODES ... SECOND BYTE IN 
(AND DECIMAL) 

110 S1$ = MID$(S$,1,1): S2$ = MID$(S$,2,1) 

120 PRINT HEX$(ASC(S1$)); ” HEX$(ASC(S2$)); 

” (”;ASC(S2$);”)” 

130 GOTO 10 



INP Function 


Returns the byte read from an input port. 


INP( port) 
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Allows input from the keyboard during program execution. INPUT is 
only used in a program. 


INPUT [ ; ] [prompt ; ]variable[ , variable]... 
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Where 


SYNTAX ELEMENT 

MEANING 


prompt 

Is a string constant enclosed in quotation marks 


which prompts you for the values you have to 
from the keyboard 

enter 

variable 

Is a numeric or string variable to which is assign- 


ed the value entered from the keyboard 



Characteristics 

When an INPUT statement is encountered, program execution pauses 
and a question mark is printed to indicate the program is waiting for 
data. If prompt is included, the string is displayed before the ques¬ 
tion mark. The required data is then entered at the terminal. 

A comma may be used instead of a semicolon after the prompt string 
to suppress the question mark. 

If INPUT is immediately followed by a semicolon, then the CR typed 
by the user to input data does not echo a CR LF sequence. 

The data that is entered is assigned to the variable(s) given in the 
variable list. The number of data items supplied must be the same as 
the number of variables in the list. Data items must be separated by 
commas. 

The variable names in the list may be numeric or string variable names 
(including subscripted variables). The type of each data item that is 
input must agree with the type specified by the variable name. (Strings 
input to an INPUT statement need not be surrounded by quotation 
marks.) 
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Responding to INPUT with too many or too few items or with the wrong 
type of value (numeric instead of string, etc.) causes the message 
”?Redo from start” to be printed. No assignment of input values is 
made until an acceptable response is given. 

You may use all the GW-BASIC screen editor features in responding 
to INPUT and LINE INPUT statements. 

Note that CTRL C or CTRL BREAK may be used to break out of an 
INPUT statement. 


Example 
10 INPUT X 

20 PRINT X ’’SQUARED IS” Xa2 
30 END 

RUN 
? 5 

5 SQUARED IS 25 
Ok 


Example 

LIST 

10 PI = 3.14 

20 INPUT ’’WHAT IS THE RADIUS”;R 
30 A = PI*R a 2 

40 PRINT ’’THE AREA OF THE CIRCLE IS”;A 
50 PRINT 
60 GOTO 20 
Ok 

RUN 

WHAT IS THE RADIUS? 7.4 

THE AREA OF THE CIRCLE IS 171.9464 

WHAT IS THE RADIUS? 
etc. 





INPUT # Statement 


Reads data items from a sequential disk file and assigns them to pro¬ 
gram variables. INPUT# is usually used in a program. 


INPUT# filenum , variable [ , variable]... 


Where 


SYNTAX ELEMENT 

MEANING 

• 

filenum 

Is the number used when the file was OPENed for 
input 


variable 

Is a numeric or string variable which will receive 
a data item from the file. (The type of data in the 
file must match the type specified by the variable 
name.) With INPUT #, no question mark is printed, 
as with INPUT. 


Characteristics 



The data items in the file should appear just as they would if data were 
being typed in response to an INPUT statement. With numeric values, 
leading spaces, carriage returns, and line feeds are ignored. The first 
character encountered that is not a space, carriage return, or line feed 
is assumed to be the start of a number. The number terminates on 
a space, carriage return, line feed, or comma. 

• 
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If GW-BASIC is scanning the sequential data file for a string item, 
leading spaces, carriage returns, and line feeds are also ignored. The 
first character encountered that is not a space, carriage return, or line 
feed is assumed to be the start of a string item. If this first character 
is a quotation mark (”), the string item will consist of all characters 
read between the first quotation mark and the second. Thus, a quoted 
string may not contain a quotation mark as a character. If the first 
character of the string is not a quotation mark, the string is an unquoted 
string, and will terminate on a comma, carriage return, or line feed (or 
after 255 characters have been read). If end-of-file is reached when 
a numeric or string item is being INPUT, the item is terminated. 

Note that CTRL Z is permitted as a character when reading from 
“KYBD:”, Thus the program: 

10 OPEN “KYBD:” FOR INPUT AS 1 

20 INPUT #1, A$ 

30 GOTO 20 

can be interrupted only by using CTRL BREAK. 


Example 

100 INPUT #1,X$,Y$,Z$ 

This example uses the INPUT # statement to read data from a sequen¬ 
tial file into the program. 


INPUT$ Function 


Returns a string of characters read from the standard input device, 
the keyboard, or from a file. 

INPUTS is usually used in a program. 


INPUT$( length[ , [ # ]filenum] ) 












Where 


SYNTAX ELEMENT 

MEANING 

length 

Is an integer expression specifying the number of 
characters to be read from the keyboard or a file. 

filenum 

Is the file number specifying the file to be read. If 
you omit filenum , the keyboard is read by default. 

Characteristics 


If the keyboard is used for input, no characters will be displayed on 
the screen. All characters (including control characters) are passed 
through except CTRL BREAK and CTRL C, which are used to interrupt 
the execution of the INPUTS function. 

The INPUTS function is preferred over INPUT# and LINE INPUT# 
statements, when reading COM files, since all ASCII characters may 



be significant in communications. INPUT # is less desirable because 
input stops when a comma (,) or CRis encountered and LINE INPUT# 
terminates when a CR is encountered. 


Example 1 


5 

10 

20 

30 


’LIST THE CONTENTS OF A SEQUENTIAL FILE IN 

HEXADECIMAL 

OPEN’T’,1 ,”DATA” 

IF EOF(1) THEN 50 

PRINT HEX$(ASC(INPUT$(1, # 1))); 
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40 GOTO 20 
50 PRINT 
60 END 


Example 2 


100 PRINT ’’TYPE P TO PROCEED OR S TO STOP” 
110 X$ = INPUT$(1) 

120 IF X$ = ”P” THEN 500 

130 IF X$ = ”S” THEN 700 ELSE 100 


Example 3 

This sequence of statements may be used to read a communications 
file: 

10 WHILE NOT EOF(1) 

20 A$ = INPUT$(LOC(1), # 1) 

30 ... 

40 ... Process data returned in A$ ... 

50 ... 

60 WEND 

The above sequence of statements read: ”.. While there is something 
in the output queue, return the number of characters in the queue and 
store them in A$. If there are more than 255 characters, only 255 will 
be returned at a time to prevent ’’String Overflow”. Further, if this is 
the case, EOF(1) is false and input continues until the input queue is 
empty..” 


INSTR Function 


Searches for the first occurrence of a given substring in a string, and 
returns the position at which the match is found. 


INSTR( [start , [string , substring ) 


Where 


SYNTAX ELEMENT 

MEANING 

A 

start 

Is an integer expression in the range 1 to 255, 
which specifies where the search is to begin. If 
omitted, 1 is assumed. 

string 

Is a string expression (in particular a string 
tant or variable) whose value is the string 
searched 

cons- 

to be 

substring 

Is a string expression (in particular a string < 
tant or variable) whose first occurrence is 
searched for 

cons- 

to be 


• 
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Characteristics 

IF... 

THEN... 

start >LEN (string) 

the returned value is 0 

start < 1 or start 
>255 

an error is returned (Illegal function call) 

string is empty (null 
string) 

the returned value is 0 

substring cannot be 
found 

the returned value is 0 

substring is empty 
and start is specified 

the returned value is start. 

substring is empty 
and start is omitted 

the returned value is 1 


Example 

10 X$ = ’’ABCDEB” 

20 Y$ = ”B” 

30 PRINT INSTR(X$,Y$);INSTR(4,X$,Y$) 
RUN 
2 6 
Ok 















Note that the position at which the match is found is always evaluated 
from the beginning of the original string, even if start is specified. 


INT Function 


Returns the largest integer that is equal to, or less than the argument. 


INT( numexp ) 


Characteristics 


Refer to the CINT and FIX functions, which also return integer values. 


Examples 

PRINT INT(99.89) 

99 

Ok 


PRINT INT(-12.11) 

-13 

Ok 


IOCTL Statement 


Sends a ’’Control Data” string to a Character Device Driver anytime 
after the Driver has been OPENed. IOCTL is usually used in a program. 


GW-BASIC INTERPRETER USER GUIDE 


8-158 



























COMMANDS, STATEMENTS AND FUNCTIONS 



IOCTL [ # ]filenum , string 

Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the file number open to the Device Driver 

string 

Is a string expression containing the Control Data 


Characteristics 


IOCTL commands are generally 2 to 3 characters optionally followed 
by an alphanumeric argument. An IOCTL command string may be up 
to 255 bytes long. 

The IOCTL statement works only if: 

1. The device driver is installed. 

2. The device driver processes IOCTL strings. 

3. GW-BASIC performs an OPEN on a file on that device. 


Most standard MS-DOS device drivers don’t process IOCTL strings, 
and it is necessary for the programmer to determine whether the 
specific driver can handle the command. 


If a user has installed his own Driver to replace LPT1, and that Driver 
is able to set Page Length, then an IOCTL command to set or change 
the page length might be: 

PL/7 


where n is the new page length. 















Example 


Opening the new LPT1 driver and setting the Page Length to 66 lines 
would then be: 


10 OPEN ”LPT1:” FOR OUTPUT AS #1 
20 IOCTL # 1 ,”PL66” 


Example 


10 OPEN ”\DEV\LPT1 ” FOR OUTPUT AS #1 
20 IOCTL # 1 ,”PL56” 

Also open LPT1, but with an initial Page Length of 56 lines. 

Other user definable IOCTL commands are possible, such as, PTn 
(set Print Tabs every n spaces). 


Possible Errors 


’’Bad file number” - IOCTL to a Driver that is not OPEN. 
’’Illegal function call” - If Device does not support IOCTL. 
’’Device Fault” - If error in Control Data. 
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IOCTL$ Function 


Returns a ’’Control Data” string from a Character Device Driver that 
is OPEN. IOCTL$ is usually used in a program. 


IOCTL$([# ]filenum ) 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the file number open to the device 


Characteristics 

The IOCTL$ function is most frequently used to receive acknowledge¬ 
ment that an IOCTL statement succeeded or failed, or to obtain cur¬ 
rent status information. 

IOCTL$ could be used to ask a communications device to return the 
current baud rate, information on the last error, logical line width, etc. 

The IOCTL$ function works only if: 

1. The device driver is installed. 

2. The device driver processes IOCTL strings. 












3. GW-BASIC performs an OPEN on a file on that device. 
Also see the IOCTL statement. 


Example 

10 OPEN ”\DEV\FN1 ” AS #1 

20 IOCTL # 1 ,”RAW” Tell device that data is ’’RAW” 

30 IF IOCTL$(1) = ”0” THEN CLOSE 1 

If Character Driver FN1 gives a false return from the Raw data mode 
IOCTL request, then close the files and stop processing. 


Possible Errors 


’’Bad file number” 
’’Illegal function call” 


KEY Statement 


- IOCTL to a Driver that is not OPEN. 

- If Device does not support IOCTL. 


Sets a function key to automatically type any sequence of characters. 
Other options allow you to enable or disable the function key display 
from the 25th line, or to list the function key values. 


KEY| OFF | ON | LIST | n , stringexp J 
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Where 

SYNTAX ELEMENT 

MEANING 

n 

Is the ’key number’. An expression returning an un¬ 
signed integer in the range 1 to 10 

stringexp 

Is a string expression assigned to the key. String 
constants should be enclosed in quotation marks. 
The stringexp value may be up to 15 characters 
long. Longer strings are truncated to 15 characters. 



Remarks 


The KEY statement enables the designation of a function key as a sof¬ 
tkey. This means that you can set any function key to generate any 
sequence of characters. 


STATEMENT 

MEANING 

KEY OFF 

Erases the softkey display from the bottom line, 
making this line available for your GW-BASIC pro¬ 
gram. In this case you can use LOCATE 25,1 
followed by PRINT to display data on the bottom 
line of the screen. KEY OFF does not disable the 
function keys. 

















STATEMENT 


MEANING 


KEY ON 


Causes the softkey values to be displayed on the 
bottom line of the screen. If the screen width is 80, 
all ten softkeys are displayed, but only five softkeys 
are displayed if the width is 40. In either case, on¬ 
ly the first 6 characters of each key value are 
displayed. ON is the default state. 


KEY LIST 


Displays all softkey values on the screen, with all 
15 characters of each key displayed. 


KEY n,string exp 


Sets function key n 

Any one or all of the ten function keys may be 
assigned up to a 15 byte string by KEY n,stringexp. 
When the key is pressed, the associated string will 
be generated. 

Initially, the softkeys default to the following values: 


FI - LIST 
F3 - LOAD” 

F5 - CONT CR 
F7 - TRON CR 
F9 - KEY space 


F2 - RUN CR 
F4 - SAVE” 

F6 - ,”LPT1:” CR , 

F8 - TROFF CR 

F10 - SCREEN 0,0,0 CR 
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Remarks 

1. If the function key number is not in the range 1 to 10, an ’’Illegal 
function call” error is returned. The previous key string expres¬ 
sion is retained. 

2. The key assignment string may be 1 to 15 characters in length. 
If the string is longer than 15 characters, the first 15 characters 
are assigned. 

3. Assigning a null string (string of length 0) to a softkey disables 
the function key as a softkey. 

4. When a softkey is assigned, the INKEY$ function returns one 
character of the softkey string per invocation. 


Example 


50 KEY ON 

60 KEY OFF 

70 KEY 1 ,”MENU” + CHR$(13) 

80 KEY 2,”” 


’Display the softkeys on the 
bottom line. 

’Erase softkey display. 

’Assigns the string ’’MENU” 
CR to soft key 1. Such 
assignments might be used 
for rapid data entry. 

’Disables softkey 2 as a soft 
key. 


The following routine initializes the first 5 softkeys: 


1 

10 

20 

30 

40 

50 


KEY OFF ’Turn off key displays during init. 

DATA ’’EDIT”, ’’LEFT”, ’’SYSTEM”, ’’PRINT”, ’’LPRINT 
FOR I = 1 TO 5:READ SOFTKEYS$(l) 

KEY I, SOFTKEYS$(l) 

NEXT I 


> j 


KEY ON ’now display new softkeys. 





Defining Keys 15-20 

Defining keys 15 to 20 allows you to trap any Ctrl-Key, Shift-Key, or 
Super-Shift ( ALT )-Key. These keys are defined by the statement: 


KEY n , CHR$( shift ) + CHR$( scan-code ) 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression in the range 15 to 20 

shift 

Is a numeric value corresponding to the following 
hex values: 

CAPS LOCK &H40 (Caps Lock is active) 

NUM LOCK &H20 (Num Lock is active - 

Keyboard 2 only) 

ALT &H08 (Alt Key is pressed) 

CTRL &H04 (Ctrl Key is pressed) 

Right SHIFT &H01 

Left SHIFT &H02 

Both the left and right SHIFT keys can be used, 
where values of &H01, &H02 or &H03 (the sum of 
hex 01 and hex 02) denote a SHIFT key. 

It is also possible to add multiple shift states, such 
as CTRL and ALT keys together, by adding the 
associated shift state values. 

scan-code 

Is a decimal number in the range 1 to 83 on 
Keyboard 1 and 1 to 103 on Keyboard 2. It 
represents the scan code (in decimal) of the key 
to be trapped. 
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Remarks 

Trapped keys are processed in the following order: 

1. CTRL PRT SC. Note that CTRL PRT SC, even if defined as a trappable 
key, will still produce a printed copy of all text sent to the screen. 

2. The function keys FI to F10, and the cursor direction key. Defin¬ 
ing a function key or cursor movement key as a user defined key 
trap will have no effect as they are considered pre-defined. 

3. The user defined keys are examined (15-20). 

Any key that is trapped is not passed to GW-BASIC, i.e., it does not 
go into the keyboard buffer. This applies to any key, including 
CTRL BREAK or CTRL ALT DEL. This makes it possible to prevent GW- 
BASIC users from accidentally interrupting a program or rebooting the 
system. 


Examples 

See the ON KEY(/i) GOSUB statement. 


KEY(n) Statements 


KEY(n) ON enables, KEY(n) OFF disables, and KEY(n) STOP suspends 
event trapping of the specified key. The KEY(n) statement is usually 
used in a program. 


KEY( n ) [ON | OFF | STOP] 










Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression from 1 to 20. It specifies 
the number of a function key (if it is from 1 to 10), 
or a cursor direction key (11 to 14), or a user defin¬ 
ed key (15 to 20). The cursor direction keys are:‘ 

cursor up (11), cursor left (12), cursor right (13), and 
cursor down (14). 

User defined keys are specified with the formula: 

KEY n, CHR$(shift) + CHR$(scan-code) 

See the KEY statement. 

To Enable or Disable KEY(n) Trapping 

IF... 

THEN... 

a KEY(n) ON is ex¬ 
ecuted 

KEY(n) trapping is enabled. 

a KEY(n) OFF is ex¬ 
ecuted 

KEY(n) trapping is disabled. 
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IF... 

THEN... 

a KEY(n) STOP is ex¬ 
ecuted 

KEY(/?) trapping is suspended. If KEY(n) is press¬ 
ed the event is remembered, and the trapping 
routine will be activated as soon as a KEY(n) ON 
is executed. 

an ON KEY(n) 

GOSUB is executed 

KEY(n) trapping is suspended. 

an error trap takes 
place 

all trapping is automatically disabled. 

Example 


10 KEY 4, ’’SCREEN 0,0,0” ’assign softkey 4 
20 KEY (4) ON ’enables KEY trapping 


100 ON KEY (4) GOS.UB 1000 


Key 4 pressed 


1000 REM KEY (4) Trap Routine 











KILL Command 


Deletes a disk file. 


KILL [filespec | pathname] 


Where 


SYNTAX ELEMENT 

MEANING 


filespec 

or 

pathname 

Is a string expression which specifies the file to 
be deleted. The filename must include the exten¬ 
sion if one exists. 



Characteristics 

KILL checks to see if the file is open, and if so will give a ’’File already 
open” error. KILL, like OPEN, cannot distinguish a file in another direc¬ 
tory from one you may have open. It is possible to get an unexpected 
’’File already open” error under these circumstances. 

KILL can only be used to delete a file. You must use the RMDIR com¬ 
mand to remove a directory. 


Warning 


The filename may contain question marks (?) or asterisks (*) used as 
wildcards. Be extremely careful when using wildcards with this 
command. 
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Example 

200 KILL ”A:DATA1.DAT” 

300 KILL ”C:DIR1 \DIR2\PROG2.BAS” 

Note that the filename must include the extension, if one exists. GW- 
BASIC does not supply the extension .BAS for the KILL command. 


LCOPY Command 


Prints the contents of the screen (text and or graphics). To print 
graphics you must have a graphics printer and have executed the MS- 
DOS GRAPHICS command before having entered GW-BASIC. 


LCOPY [n] 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is a dummy argument. Any value may be supplied. 
This parameter is allowed only for compatibility with 
other BASICS, where it may specify to copy either 
text or graphics. 





















LEFT$ Function 


Returns a substring extracting a number of characters to the left of 
a given string, as specified by the length parameter. 


LEFT$( string , length ) 


Where 



MEANING 


SYNTAX ELEMENT 


Is a string expression whose value is the string from 
which the substring is to be returned 


string 


Is an integer expression (from 0 to 255) which 
specifies the number of the characters to be 
returned. 


length 


Characteristics 

If length is greater than LEN (string), the entire original string will 
be returned. If length = 0, the null string (length zero) will be 
returned. 

Refer to the MID$ and RIGHTS functions. 
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Example 

LIST 

10 A$ = ”GW-BASIC” 
20 B$ = LEFT$(A$,6) 
30 PRINT B$ 

RUN 

GW-BAS 

Ok 


LEN Function 


Returns the length of a given string. 

LEN( stringexp ) 


Where 


SYNTAX ELEMENT 

MEANING 

stringexp 

Is any string expression, whose length will be 
returned 


Characteristics 

Unprintable characters and blanks are counted in the number of 
characters. If the argument stringexp is a null string, LEN returns 
zero. 














Example 


10 X$ =’’PORTLAND, OREGON” 
20 PRINT LEN(X$) 

RUN 

16 

Ok 


LET Statement 


Assigns a value to a variable. 


[ LET ] variable = expression 


Where 


SYNTAX ELEMENT 

MEANING 

variable 

Is a numeric or string variable which will receive 
the value of the expression. 

expression 

Is the expression to be evaluated and assigned to 
the variable on the left side of the equal sign 
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Characteristics 

The type of the expression (numeric or string) must match the type 
of the variable ; if not, a ’’Type Mismatch” error occurs. However in 
numeric assignments the type of the expression (integer, single preci¬ 
sion or double precision) may be different from the type of the destina¬ 
tion variable. In this case GW-BASIC converts the expression value 
to the type of the variable. Rounding or overflow may occur in this con¬ 
version. 

The word LET is optional. The equal sign is sufficient when assigning 
an expression to a variable name. 


Examples 

110 LET D = 12 
120 LET E = 12 a 2 
130 LET F = 12 a 4 
140 LET SUM = D + E + F 
150 A(l) = 300 
160 A$(K) = ’’ABC” 


Note that the word LET is optional (see the statements in lines 150 
and 160 above). 


LINE Statement 


Draws either a line or a rectangle, or a filled rectangle (Graphics Mode 
only). 


LINE [[ STEP ](x1,y1)]- [STEP ](x2,y2)[, [color] [ ,B[ F]][, style]] 










Where 


SYNTAX ELEMENT 

MEANING 

(xf ,y1),(x2,y2) . 

Represent absolute coordinates, or relative coor¬ 
dinates. The STEP option indicates relative coor¬ 
dinates. If (x1,y1) is omitted the last referenced 
point is assumed. 

color 

Is the color number specifying the color in which 
the line or rectangle will be drawn (in the range 0 
to 3). In Medium Resolution, color choses a color 
from the active palette; in High and Super Resolu¬ 
tion, a value for color of 0 or 2 selects black and 
a value of 1 or 3 selects white. If color is omitted 
the color used will correspond to the value given 
for the gforeground parameter in the most recent¬ 
ly executed COLOR statement; if this parameter 
has not been specified, 3 is assumed for Medium 
Resolution and 1 for High and Super Resolution. 

B 

Specifies the drawing of a rectangle. 

F 

Specifies the drawing of a filled rectangle. 

style 

Is a 16-bit parameter, normally given in hex¬ 
adecimal format, that specifies the “style” of the 
line. It has no effect if BF has been specified. 


Characteristics 

The following example draws a line from the last point referenced to 
the point specified (x2,y2). Since no color is specified, the default col¬ 
or is the foreground color. 

LINE -(x2,y2) 
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The examples below specify start and end points in absolute coor¬ 
dinates. 

LINE (10,10)-(319,199) 

draws a diagonal line down the screen 
LINE (10,100)-(319,100) 
draws a horizontal line across the screen 

You can specify the color number in which the line is drawn: 

LINE (15,15)-(25,25),2 

draws a line in color 2 of the active palette. 

The B parameter is used to draw a rectangle, where the points (xl ,y1) 
and (x2,y2) represent the opposite corners. In the following example, 
no color number is specified: 

LINE (10,10)-(100,100),,B 

draws a box 

Color may be included as follows: 

LINE (10,10)-(200,200),2,BF 

filled box color 2 

The B parameter facilitates the drawing of rectangles, which would 
otherwise require the following lengthy programming format: 

LINE (Xl,y1)-(x2,y1) 

LINE (x1,y1)-(x1,y2) 

LINE (x2,y1)-(x2,y2) 

LINE (Xl,y2)-(x2,y2) 

The BF options fills the interior of the rectangle with the selected color. 

If the STEP option is specified for the second pair of coordinates, they 
are taken as relative to the first pair of coordinates. For example: 

LINE(50,50) -STEP(15,-13) 

draws a line from (50,50) to (65,37). 




Line Styling 

The style parameter can also be specified in the LINE statement. It 
is a 16-bit integer value, used to specify a mask for the style of a line. 
style can be used for drawing both lines and rectangles. 

Before LINE plots a pixel on the screen, the value of the current bit 
in style is used. If the bit equals 0, the color of the pixel is unchanged; 
if the bit equals 1, the pixel is plotted with the color specified. For each 
successive pixel the successive bit-position in style is used. When the 
whole mask has been scanned, scanning restarts at the beginning of 
the mask, until the entire line is drawn. 

Since a bit equal to 0 in style does not modify the color of the pixel 
on the screen, it can be useful to draw a line of a specific color, before 
overlaying it with a ’’styled” line, in order to have the correct 
background color for the line you wish to draw. 


Example 

LINE (0,0)-(160,100),3„&HFF00 

Draws a dashed line from the upper left hand corner to the screen 
center, assuming a screen 320 pixels wide by 200 pixels high. 


- LINE INPUT Statement 


Inputs an entire line (up to 254 characters) to a string variable, without 
the use of delimiters. A LINE INPUT statement is only used in a 
program. 


LINE INPUT[;] [prompt ; ]stringvar 
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Where 

SYNTAX ELEMENT 

MEANING 

prompt 

Is a string constant (enclosed in a pair of quota¬ 
tion marks) that is displayed on the screen before 
input is accepted. A question mark is not displayed 
unless it is part of the ’’prompt string”. 

stringvar 

Is the name of a string variable to which the line 
will be assigned. 



Characteristics 

All input from the end of prompt to the CR is assigned to 
stringvar. Trailing blanks are ignored. If a LF CR is encountered, 
both characters are echoed, but the CR is ignored, the LF is put 
into stringvar , and data input continues. 


If LINE INPUT is immediately followed by a semicolon, then the 
CR typed to end the input line does not echo a CR LF sequence 
on the screen. 

A LINE INPUT statement may be aborted by typing CTRL BREAK . 
GW-BASIC will return to command level and type ”Ok”. Typing CONT 
resumes execution at the LINE INPUT. 

You may use all the GW-BASIC screen editor features in responding 
to INPUT and LINE INPUT statements. 


Example 


See LINE INPUT # statement. 



8-179 










LINE INPUT# Statement 


Reads an entire line (up to 254 characters), without delimiters, from 
a sequential disk data file to a string variable. LINE INPUT# is usual¬ 
ly used in a program. 


LINE INPUT # filenum , stringvar 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the number under which the file was OPENed 

stringvar 

Is the string variable to which the line will be 
assigned 


Characteristics 

LINE INPUT# reads all characters in the sequential file up to a CR . 
It then skips over the CR LF sequence. The next LINE INPUT# 
reads all characters up to the next CR . (If a line LF CR sequence 
is encountered, it is preserved.) 

LINE INPUT # is especially useful if each line of a data file has been 
broken into fields, or if a GW-BASIC program saved in ASCII format 
is being read as data by another program. (See ’’SAVE,” in this 
chapter.) 
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Example 

10 OPEN ”0”,1,”LIST” 

20 LINE INPUT ’’CUSTOMER INFORMATION? ”;C$ 

30 PRINT # 1, C$ 

40 CLOSE 1 
50 OPEN ”l”,1 ,”LIST” 

60 LINE INPUT #1, C$ 

70 PRINT C$ 

80 CLOSE 1 
RUN 

CUSTOMER INFORMATION? LINDA JONES 234,4 MEMPHIS 
LINDA JONES 234,4 MEMPHIS 
Ok 


LIST Command 


Lists the current program to the screen or a specified file or device. 
LIST is usually used in immediate mode. 


LIST [linenuml ][ - [linenum2]][ , [device | filespec \pathname]] 









Where 


SYNTAX ELEMENT 

MEANING 


linenuml and 

Iinenum2 

Are the line numbers of the first and the last line 
to be listed. You may use a period (.) for either line 
number to indicate the current line. 

device or 
filespec or 
pathname 

Is a string expression for the device specification 
(or for the file specification). 


Characteristics. 

If you omit the device or filespec or pathname the listing is directed 
to the screen. You can stop listings directed to either the screen or 
the printer by pressing CTRL BREAK at any time. You cannot interrupt 
listings directed to a file or device: in this case the listing will continue 
until the range is exhausted. 

CTRL NUM LOCK (or CTRL FUNCT LOCK) causes the listing to pause until 
another key is pressed. 

If you omit the line range, the complete program will be listed. 

The syntax allows the following options: 

• If only linenuml - is given, that line and all higher numbered lines 
are listed. 

• If only Iinenum2 - is given, all lines from the beginning of the pro¬ 
gram through the given line are listed. 

• If both numbers are specified, the inclusive range is listed. 

When you direct a listing to a disk file, the program is saved in ASCII 
format, thus you may later use this file with MERGE. 
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Examples 
LIST , LPT1: 

. List the program to the Line Printer. 

LIST 10-90 

List lines 10 through 90 to the Screen. 

LIST 10- , SCRN: 

List lines 10 through last to the Screen. 


LLIST Command 



Lists the current program on the printer. LLIST is usually used in im¬ 
mediate mode. 


LLIST [Iinenum1][ - [Iinenum2]] 


Characteristics 

For an explanation of the meaning of the parameters see the LIST 
command. 

LLIST assumes a 132-character-wide printer. 

GW-BASIC always returns to command level after an LLIST is ex¬ 
ecuted. 










Examples 


LUST 

Lists a complete program. 

LUST 50 

Lists line 50. 

LUST 20-40 

Lists lines 20-40 

LLIST-150 

Lists from the first program line to line 150 

LUST 90- 

Lists all lines from 90 to end of program. 


LOAD Command 


Loads a program into memory from a specified drive. You can run the 
program, if you specify the option R. 


LOAD [filespec] pathname] [ ,R ] 
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Where 

SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression which specifies the file to be 
loaded. If you do not specify a drive letter, then the 
MS-DOS default drive is assumed. 

R 

Represents RUN. It is optional and when specified 
will cause the loaded program to begin execution 
from the first statement. In this case all open data 
files are kept open. 


Characteristics 

LOAD deletes all variables and program lines currently residing in 
memory and closes all open data files before it loads the specified pro¬ 
gram. However, if option R is specified, all open data files are kept 
open and the program is run after it is loaded. 

Note that: 

RUN filespec is equivalent to LOAD filespec ,R. 
and that: 

RUN pathname is equivalent is LOAD pathname ,R. 


Example 

LOAD ”STRTRK”,R 

Loads and runs the program STRTRK.BAS 

LOAD ”B:MYPROG” 

Loads the program MYPROG.BAS from the disk in drive B, but does 
not run the program. 









LOC Function 


Returns the current position in the file. LOC is usually used in a 
program. 


LOC( filenum ) 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the number under which the file was OPENed 


Characteristics 

For random disk files, LOC returns the record number just read or writ¬ 
ten from a GET or PUT statement. 

For sequential files, LOC returns the current byte position in the file, 
divided by 128. 

When a file is opened for APPEND or OUTPUT, LOC returns the size 
of the file in (bytes/128). 
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For communications files LOC is used to determine if there are any 
characters in the input queue waiting to be read. The input queue can 
hold more than 255 characters (determined by the /C: switch). If there 
are more than 255 characters in the queue, LOC returns 255. Since 
strings are limited to 255 characters, this practical limit removes the 
need to test for string size before reading data into them. If fewer than 
255 characters remain in the queue, the value returned by LOC 
depends on whether the device was opened in ASCII or binary mode. 


In either mode, LOC will return the number of characters that can be 
read from the device. However, in ASCII mode, the low level routines 
stop queueing characters as soon as end-of-file is received. The 
character which indicates the end-of-file itself is not queued and can¬ 
not be read. An attempt to read the end-of-file will result in an ’’Input 
past end” error. 


Example 


100 IF LOC(2) > 100 THEN STOP 


LOCATE Statement 


Moves the cursor to the specified position on the active page. In Text 
mode LOCATE may also turn the cursor on and off and define the 
size of the cursor. 


LOCATE [row][ , [column][ , [cursor][ , [start][ , stop]]]] 
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Where 





SYNTAX ELEMENT 

MEANING 


row 

Is the screen line number. A numeric expression 
returning an unsigned integer in the range 1 to 25. 


column 

Is the screen column number. A numeric expres¬ 
sion returning an unsigned integer in the range 1 
to 80, depending upon screen width. 


cursor 

Is a boolean value indicating whether the cursor 
is visible or not during program execution. A zero 
value turns the cursor off, a nonzero value (say 1) 
turns the cursor on. This parameter can only be us¬ 
ed in Text Mode. 

• 

start 

Is a numeric expression whose integer value 
represents the cursor top (starting) scan line. 
Values allowed are between 0 and 7. This 
parameter can only be used in Text Mode. 


stop 

Is a numeric expression whose integer value 
represents the bottom (stop) cursor scan line. It has 
the same range of values as start , but must be 
greater than or equal to start ; if it is equal the cur¬ 
sor will be shown as a single scanline. If this 
parameter is omitted, and start is given, stop 
defaults to the value of start. This parameter can 
only be used in Text Mode. 


Characteristics 


• 

If any of the parameters used with LOCATE are omitted, the current 
value is assumed. 
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Placing Characters on Line 25 

Normally, GW-BASIC will not print to line 25 because of the soft key 
display. This can be turned off, however, using KEY OFF; you can then 
use LOCATE 25,1: PRINT... to display characters on line 25. 


Examples 

100 LOCATE 1,1 

Moves the cursor to the home position in the upper left-hand corner. 
200 LOCATE „1 

Makes the cursor visible; its position remains unchanged. 

300 LOCATE „0 
Turns the cursor off. 

400 LOCATE 6,1,1,0,7 

Moves the cursor to line 6, column 1. Makes the cursor visible, cover¬ 
ing the entire character cell, starting at scan line 0 and ending on scan 
line 7. 


Possible Errors 

Any values entered outside of the ranges indicated will result in an “il¬ 
legal function call” error. Previous values are retained. 


LOCK Statement 


The LOCK statement restricts access by other processes to all or part 
of an opened file. This statement is only of use if MS-NET is installed 
with MS-DOS release 3.1 or later. 


LOCK [#] filer)um [ , [recordnuml] [TO recordnum2 ]] 









Where 


SYNTAX ELEMENT 


filenum 


recordnuml 


recordnum2 


MEANING 


Is the file number of the opened file. 


Is the number of the record at which locking begins. 
If this parameter is omitted record number 1 is 
assumed. 


Is the number of the record at which locking ter¬ 
minates. If this parameter is omitted, only one 
record ( recordnuml) is locked. 


Characteristics 

If the file has been opened for sequential input or output, the entire 
file is locked regardless of any range specified. If the file is opened 
in random mode, the range indicates which records are to be locked. 

See also the UNLOCK and OPEN statements. 

Note 

If you try and use this statement with an MS-DOS release prior to 3.1 
you will get an “Advanced Feature Error”. If you are using MS-DOS 
3.1 or later, but MS-NET is not installed, you will get a “Permission 
Denied” error. The MS-DOS command SHARE must also be given 
(either at the MS-DOS prompt or from an AUTOEXEC.BAT file). See 
the “MS-DOS User Guide” for a full description of procedures to be 
followed for networking. 

The suggested usage of files on shared devices is for a LOCK to be 
executed on a file, or record range within a file, before an attempt is 
made to read or write to that file. It is also recommended that the file 
or range be UNLOCKed before the file is closed (failure to do so may 
cause problems for future access to that file in a network environment). 
The time in which files are locked should be kept to minimum. 
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Examples 

LOCK #1 
LOCK #1, 2 
LOCK #1, TO 23 
LOCK #1, 12 TO 24 

Possible Errors 

“Permission Denied”: MS-NET non installed or access to file already 
restricted. 

“Illegal Function Call”: record range specified does not meet necessary 
criteria, or range/record length combination exceeds the legal 
limit for the size of a file. 


’locks the whole of file #1 
’locks record 2 of file #1 
’locks records 1 to 23 of file #1 
’locks records 12 to 24 of file #1 


LOF Function 


Returns the length of the specified file in bytes. 


LOF( filenum ) 


Characteristics 

For random and sequential files, LOF returns the size of the file in bytes. 
Note that, when a file is opened for APPEND or OUTPUT, LOF returns 
the size of the file divided by 128. 

For communications files, LOF may be used to check if the input buf¬ 
fer is getting full as it returns the amount of free space in the input 
buffer. That is: 

buffer-size - LOF (filenum) 

where buffer-size is the size of the communications buffer. It 
defaults to 256 bytes, but may be changed with the "1C:” option in 
the GWBASIC command line. 











Example 

10 OPEN ”B:MYFILE” AS #2 
20 GET #2,LOF(1)/128 


The above statements will get the last record of the file MYFILE 
(residing on the diskette inserted in drive B) assuming that the file was 
created with a record length of 128 bytes. 


Example 

100 IF REC * RECSIZ> LOF(1) THEN PRINT ’’INVALID ENTRY” 

In this example, the variables REC and RECSIZE contain the record 
number and record length, respectively. The calculation determines 
whether the specified record is beyond the end-of-file. 


LOG Function 


Returns the natural logarithm of a positive argument. 


LOG( numexp ) 


Characteristics 

The logarithm is calculated in single precision, unless the ID option 
is supplied in the GWBASIC command line. 

If numexp is negative or zero an ’’Illegal function call” error is returned. 
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Example 

PRINT LOG(45/7) 

1.860752 
Ok 

LPOS Function 

Returns the current position of the print head within the printer buffer. 
LPOS is usually used in a program. 


LPOS( printer) 


Where 


SYNTAX ELEMENT 

MEANING 

printer 

Is an integer expression whose value (1, 2, or 3) 
indicates which printer is to be tested (LPT1:, 
LPT2:, or LPT3:). 


Remarks 

LPOS does not necessarily give the physical position of the print head. 

Example 


150 IF LPOS(1)<60 THEN LPRINT CHR$(13) 













LPRINT and LPRINT USING Statement 


LPRINT prints data in standard format on the printer. LPRINT USING 
prints data in a user-defined format on the printer. 

Syntax 1 


LPRINT [list-of-expressions ][ , | ; ] 


Syntax 2 


LPRINT USING format-string ; list-of-expressions[ , | ; ] 


Where 


SYNTAX ELEMENT 


MEANING 


list-of-expressions May include numeric and/or string expressions 

separated by commas or semicolons. 


format-string Is a string expression (usually a string constant or 

variable) that is composed of special formatting 
characters. 
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Characteristics 

These statements are the same as PRINT and PRINT USING, but the 
output goes to the printer. See PRINT and PRINT USING in this 
chapter. LPRINT assumes a 132 character-width printer. 


Example 

10 A$ = ’’For July...” 

20 X = .491 

30 LPRINT ’’Results”, A$, 

40 LPRINT X 
Ok 

RUN 

Results For July... .491 

The result appears on the line printer. 


LSET and RSET Statements ==^= 


LSET stores a string value in a random buffer field left justified, or left 
justifies a string value in a string variable. 

RSET stores a string value in a random buffer field right justified, or 
right justifies a string value in a string variable. 

LSET and RSET are usually used in a program. 

Syntax 1 


LSET stringvar = stringexp 










Syntax 2 


RSET stringvar = stringexp 


Where 


SYNTAX ELEMENT 

MEANING 

stringvar 

Represents a variable previously used in a FIELD 
statement. 

stringexp 

Represents the string to be left or right justified in 
a given field. 

Characteristics 



If stringexp requires fewer bytes than were FIELDed to 
stringvar, LSET left-justifies the string in the field, and RSET right- 
justifies the string (spaces are used to pad the extra positions). If the 
string is too long for the field, characters are dropped from the right. 
Numeric values must be converted to strings before they are LSET 
or RSET. See also Chapter 4 for a complete description of random files. 


Examples 


150 LSET A$ = MKS$(AMT) 

160 LSET D$ = MKI$(COUNT%) 
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LSET or RSET may also be used with a nonfielded string variable to 
left-justify or right-justify a string in a given field. For example, the pro¬ 
gram lines: 

110 A$ = SPACE$(20) 

120 RSET A$ = N$ 

right-justify the string N$ in a 20-character field. This can be most useful 
for formatting printed output. 


MERGE Command 


Merges a specified GW-BASIC disk file, previously saved in ASCII for¬ 
mat, with the program currenty resident in memory. 


MERGE [filespec] pathname] 


Where 


SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression which specifies a GW-BASIC 
source file, and optionally the drive on which it can 
be found. If the drive is omitted the MS-DOS default 
drive is assumed. 













Characteristics 


The MERGE command allows you to include a specified program sav¬ 
ed (in ASCII format) on a disk, with the program in memory. MERGE 
is similar to LOAD, except that the program in memory is not erased 
before the disk program is transferred into memory. Instead, the disk 
program is merged into the resident program in such a way as to make 
a single program. In other words, program lines in the disk program 
will simply be inserted into the resident program in sequential order. 
If a line of the disk program and a line of the resident program have 
the same line number, the line of the disk program replaces that of 
the resident program in memory. 


Example 

MERGE ”B:ROOT\S1 \SUBRTN” 


MID$ Function and Statement 


As a function, MID$ returns a substring from a specified string. As a 
statement, MID$ replaces a part of a string with another string. 

Syntax 1: function 


MID$( string , start[ , length]) 


Syntax 2: statement 


MID$( string , start[ , length]) = substring 
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Where: As a Function 


SYNTAX ELEMENT 

MEANING 

string 

Is a string expression whose value is the string from 
which the substring is to be returned 

start 

Is an integer expression whose value specifies the 
character position of the beginning of the return¬ 
ed string. It must be > = 1. 

length 

Is an integer expression from 0 to 255 which 
represents the length of the returned string 

Characteristics 


The function returns a substring from a specified string, starting from 
a specified character position ( start ). The length of the returned 
substring can be specified. If length is omitted or if there are fewer 
than length characters to the right of the specified character posi¬ 
tion, all rightmost characters beginning with the specified character 
position are returned. If length is equal to zero, or if start is 
greater than LEN (string), then MID$ returns a null string. 

Also see LEFTS and RIGHTS functions. 












Where: As a Statement 


SYNTAX ELEMENT 

MEANING 


string 

Is a string expression whose value is the string from 
which a substring is to be replaced. 

start 

Is an integer expression from 1 to 255, whose value 
specifies the character position where the replace¬ 
ment has to begin; start must be < = LEN (string). 

length 

Is an integer expression from 0 to 255. It represents 
the length of the returned string. 

substring 

Is a string expression which replaces the characters 
in string , beginning from start position. 

Characteristics 

The characters in string, beginning from start position, are replaced 


by the characters in substring. The optional length refers to the number 
of characters from substring that will be used in the replacement. If 
length is omitted, all of the characters of substring ere used. 

However, regardless of whether length is omitted or included, the 
replacement of characters never goes beyond the original length of 
string. 
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Examples 

The following example uses the MID$ function: 

LIST 

10 A$ = ’’HELLO ” 

20 B$ = ’’JOSEPH JOHNNY JIMMY” 

30 PRINT A$;MID$(B$,8,6) 

RUN 

HELLO JOHNNY 
Ok 

The following example uses the MID$ statement: 

LIST 

10 A$ = ’’AVIGNON, FRANCE” 

20 MID$(A$,10) = ’’ROUBAIX” 

30 PRINT A$ 

RUN 

AVIGNON, ROUBAI 
Ok 


Possible Errors 

If either start or length is out of the specified range, an “Il¬ 
legal function call” error will be returned. 


MKDIR Command 


Permits the creation of a new directory on a specified disk. 


MKDIR pathname 










Where 


SYNTAX ELEMENT 

MEANING 

pathname 

Is a string expression specifying the name of the 
directory to be created. 


Examples 


ROOT 

I 

ACCOUNTS 

AMOS ANDY 

With reference to the above tree-structure, the following statements 
will create sub-directories. 

If the current directory is the root, to create a sub-directory SALES from 
the root on the current drive, enter: 

MKDIR ’’SALES” 

To create a sub-directory called FRED under the directory SALES, 
enter: 

MKDIR ”SALES\FRED” 

To create a sub-directory called WILMA under the directory FRED, 
enter: 
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MKDIR ”SALES\FRED\WILMA” 

The resulting structure will be: 

ROOT 


FRED 


/ \ 

ES AC' 

/ / 


SALES 


ACCOUNTS 


WILMA 


AMOS ANDY 


Possible Errors 

’’Bad file name” 
’’Path/File Access error” 


MKI$,MKS$,MKD$ Functions - 


Change numeric values to string type values. 
Syntax 1 


MKI$( integer-expression ) 










Syntax 2 


MKS$( single-precision-expression ) 


Syntax 3 


MKD$( double-precision-expression ) 


Characteristics 

Any numeric value that is placed in a random file buffer with an LSET 
or RSET statement must be converted to a string. MKI$ converts an 
integer to a 2-byte string, MKS$ converts a single-precision number 
to a 4-byte string. MKD$ converts a double-precision number to an 
8-byte string. 

See also ”CVI, CVS, CVD Functions”. 


Example 

90 AMT = (K + T) 

100 FIELD #1,8 AS D$,20 AS N$ 
110 LSET D$ = MKS$ (AMT) 

120 LSET N$ = A$ 

130 PUT #1 
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NAME Command 


Changes the name of a disk file. 
Syntax 1 


NAME {filespec\pathname} AS filename 


Syntax 2 


NAME [filespec] pathname] AS new-pathname 


Where 


SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression which specifies the file to be 
renamed. The file must exist on the specified drive. 
If the drive is not specified the MS-DOS default 
drive is assumed. The file extension does not 
default to .BAS. 

filename 

Is the new name of a file to replace the old filename. 
The new name should not exist for another file. 

new-pathname 

Is a string expression which specifies the new direc¬ 
tory of the file, when NAME is used to move a file 
from one directory to another. 



















Characteristics 

After a NAME command, the file exists in the same area on the same 
disk, with the new name. Also the area allocated to the file will not 
be changed. A file may not be renamed with a new drive designation. 
If this is attempted, a ’’Rename across disks” error will be generated. 
The file must be closed before the NAME command is executed. 

NAME may also be used to move a file from one directory to another. 
For example: 

NAME ”\X\CLIENTS“ AS “\XYZ\P\CLIENTS“ 


Example 

Ok 

NAME ”B:GRAPH.BAS” AS ’’GRAPH1.BAS” 

Ok 

In this example, the file that was formerly named GRAPH.BAS on the 
diskette in drive B will now be named GRAPH1.BAS. 


Possible Errors 

’’File not found” 

’’File already exists” 
’’Bad file name” 

’’Too many files” 
’’Rename across disks” 
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NEW Command 


Deletes the current program and clears all variables, allowing you to 
enter a new program. 


NEW 


Characteristics 

NEW is entered at command level to clear memory before entering 
a new program. GW-BASIC always returns to command level after a 
NEW command is executed. NEW closes all data files and switches 
off the trace flag in the same way as TROFF. 


OCT$ Function 


Returns a string which is the octal value of the decimal argument. 


OCT$( numexp ) 













Where 


SYNTAX ELEMENT 

MEANING 

numexp 

Is a numeric expression from -32768 to 65535, 
which is rounded to the nearest integer before 


OCT$ is evaluated. 


Remarks 

When numexp is negative, the two’s complement form is used. 


Example 

PRINT OCT$(24) 

30 

Ok 

See the HEX$ function in this chapter for details on hexadecimal con¬ 
version. 


ON COM(n) GOSUB Statement 


Specifies the first line number of a subroutine to be activated as soon 
as characters arrive in the communications buffer. 

The ON COM(n) GOSUB statement is only used in a program. 


ON COM( n ) GOSUB linenum 
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Where 

SYNTAX ELEMENT 

MEANING 

n 

Is the number of the communications channel (1 
or 2). 

linenum 

Is the first line number of the trap routine. A line 
number of 0 disables the communications event 


trap. 



To Enable or Disable COM Trapping 


• 

THEN... 

a COM(n) ON is 
executed 

COM(n) trapping will be enabled. 

a COM(n) OFF is 
executed 

COM(n) trapping will be disabled. 

a COM(n) STOP is 
executed 

COM(n) trapping will be suspended i.e. should any 
characters be received, the GOSUB is not perform¬ 
ed, but will be performed as soon as a COM(n) ON 
statement is executed. 

an ON COM(n) 

GOSUB is executed 

COM(n) trapping will be suspended. 

an error trap occurs 

all trapping will be disabled (including ERROR, 
trapping). 
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To Activate a COM(n) Trapping Routine 


IF... 

THEN... 

COM(n) trapping is 
enabled, and any 
characters have come 
into the COM buffer n 

the ON COM(n) GOSUB linenum will be executed 
and the corresponding routine activated. To avoid 
recursive traps a COM(n) STOP is automatically ex¬ 
ecuted, when the trap occurs. 


A RETURN from the trap routine automatically per¬ 
forms a COM(n) ON (unless a COM(n) OFF was 
performed within the trap routine) 


The RETURN linenum form may also be used. Use 
this form with care because any other active 
GOSUB, WHILES or FORs will remain active, and 
errors (such as ’’FOR without NEXT”) may result. 


Typically, the COM trap routine will read an entire message from the 
COM port before returning. The COM trap should not be used for single 
character messages since, at high baud rates, the overhead of trapp¬ 
ing and reading for each individual character may cause the COM in¬ 
terrupt buffer to overflow. 


Example 

This example sets up a trap routine for the second communications 
channel at line 1000. 

100 ON COM(2) GOSUB 1000 
110 COM(2) ON 
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1000 REM COM activity 

1050 RETURN 200 

ON ERROR GOTO Statement 

Enables error trapping and specifies the first line number of a 
subroutine to be executed if an error occurs. 

The ON ERROR GOTO statement is only used in a program. 



ON ERROR GOTO linenum 


Where 


SYNTAX ELEMENT 

MEANING 

linenum 

Is the first line number of the error trapping routine 
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To Enable or Disable ERROR Trapping 

• 

IF... 

THEN... 


an ON ERROR 

GOTO n is executed 

ERROR trapping will be enabled, if n is not zero. 

an ON ERROR 

GOTO 0 is executed 

ERROR trapping will be disabled. Subsequent er¬ 
rors will display the associated error message and 
halt execution. 

To Activate an ERROR Trapping Routine 

• 

IF... 

THEN... 


ERROR trapping is 
enabled and a GW- 
BASIC error (or a 
user defined error) is 
found 

the ON ERROR GOTO line will be executed and 
the corresponding routine activated. The ERL and 

ERR functions are usually used in 

IF...GOTO...ELSE or IF...THEN...ELSE statements 
to direct program flow within an error trapping 
routine. 

It is recommended that the error trapping routine 
execute an ON ERROR GOTO 0 if an error is found 
for which there is no recovery action (in this case 
the standard error message will be displayed and 
execution will stop). The RESUME statement will 
resume execution after the error handling routine 
has been entered (see the RESUME statement). 
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IF... 

THEN... 

a GW-BASIC error (or 
a user-defined error) 
is found, during the 
execution of an error 
trapping routine 

the associated error message is displayed and ex¬ 
ecution terminates. Note: Once an error trap takes 
place, all trapping is automatically disabled. 

Example 


10 ON ERROR GOTO 100 
20 INPUT R 

30 IF R < = 0 THEN ERROR 200 


100 IF ERR = 200 THEN PRINT’’RADIUS NEGATIVE OR ZERO” 

110 IF ERL = 30 THEN RESUME 20 
120 ON ERROR GOTO 0 











.GOSUB and ON...GOTO Statements 


ON...GOSUB calls one of several specified subroutines, depending 
on the value of a specified expression. ON...GOTO branches to one 
of several specified line numbers, depending on the value of a specified 
expression. 

The ON...GOSUB and ON...GOTO statements are usually used in a 
program. 

Syntax 1 


ON numexp GOSUB linenum [ , linenum]... 


Syntax 2 


ON numexp GOTO linenum [ , linenum]... 


Where 

SYNTAX ELEMENT 

MEANING 

numexp 

Is a numeric expression (from 0 to 255) which deter¬ 
mines which line number in the list will be used for 
branching. If numexp is not an integer, it will be 
rounded up to an integer. 

linenum 

Is the line number to which the branch will be made. 
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Characteristics 

In the ON...GOSUB statement, each line number in the list must be 
the first line number of a subroutine. 

If the value of numexp is 1 the subroutine at the first line number 
in the list will be called, a value of 2 causes the subroutine at the se¬ 
cond line number in the list to be called and so on. If the value of 
numexp is zero or greater than the number of items in the list (but 
less than or equal to 255), GW-BASIC continues with the next ex¬ 
ecutable statement. 

If the value of numexp is negative or greater than 255, an’’Illegal 
function call” error occurs. 


Example 

100 ON L-1 GOTO 150,300,320,390 


ON KEY(n) GOSUB Statement 


Specifies the first line number of a subroutine to be executed when 
a specified key is pressed. The ON KEY(n) GOSUB statement is only 
used in a program. 


ON KEY ( n ) GOSUB linenum 









Where 

SYNTAX ELEMENT 

MEANING 

n 

Is an integer from 1-20. It specifies the key to be 
trapped as follows: 1-10 function keys FI to F10, 
11 Cursor Up, 12 Cursor Left, 13 Cursor Right, 14 
Cursor Down, 15-20 Keys defined in the form: KEY 
n, CHR$(s/j/ft) + CH R$(scan code). 

linenum 

Is the first line number of the routine that is to be 
performed when the specified function or cursor 
direction key is pressed. A line number of 0 disables 
the event trap. 

To Enable or Disable KEY(n) Trapping 

IF... 

THEN... 

KEY(n) ON is 
executed 

KEY(n) trapping will be enabled. 

KEY(n) OFF is 
executed 

KEY(n) trapping will be disabled. 

KEY(n) STOP is 
executed 

KEY(n) trapping will be suspended, i.e. should a 
specified key be pressed, the GOSUB is not per¬ 
formed, but it will be performed as soon as a KEY(n) 
ON is executed. 
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IF... 

THEN... 

an ON KEY(n) 

KEY(n) trapping will be suspended. 

GOSUB is executed 


an error trap occurs 

all trapping will be disabled. 


To Activate a KEY(n) Trapping Routine 


IF... 

THEN... 

KEY(n) trapping is 

ON KEY(n) GOSUB is executed and the correspon¬ 

enabled, and key n 

ding routine activated. 

was pressed 

To avoid recursive traps a KEY(n) STOP is 
automatically executed, when the trap occurs. A 
RETURN from the trap routine automatically per¬ 
forms a KEY(n) ON (unless a KEY(n) OFF was per¬ 
formed within the trap routine). The RETURN 
linenum form may also be used. Use this form with 
care, because any other active GOSUBs, WHILES, 
or FORs will remain active, and errors may result. 















Remarks 


When a key is trapped, the event is not memorized. Therefore, you 
cannot subsequently use the INPUT or IN KEYS statements to find out 
which key caused the trap. So if you wish to assign different functions 
to particular keys, you must set up a different subroutine for each key, 
rather than assigning the various functions within a single subroutine. 


Example 

10 KEY 4,’’SCREEN 0,0” ’assigns softkey 4 
20 KEY(4) ON ’enables event trapping 


70 ON KEY(4) GOSUB 200 

key 4 pressed 


200 ’Subroutine for screen 


250 RETURN 

In the above, the normal function associated with function key 4 is over¬ 
riden, and replaced with ’’SCREEN 0,0”, which will be displayed 
whenever that key is pressed. The value may be reassigned and it will 
resume its standard function when the system is rebooted. 


Example 

100 KEY 15, CHR$(&H04) + CHR$(83) 

105 REM ** Key 15 now is CTRL DEL ** 
110 KEY(15) ON 
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1000 PRINT ”lf you want to stop processing for a break” 

1010 PRINT ’’press the CTRL key and DEL at the” 

1020 PRINT ’’same time.” 

1030 ON KEY(15) GOSUB 3000 

The user presses CTRL DEL 

3000 REM ** Suspend processing loop. 

3010 CLOSE #1 
3020 RESET 
3030 CLS 

3035 PRINT ’’Enter CONT to continue.” 

3040 STOP 

3050 OPEN ”A”, #1, ’’ACCOUNTS.DAT” 

3060 RETURN 

In the above, the CTRL DEL key is enabled to enter a subroutine 
which closes the files and stops program execution until the operator 
is ready to continue. 


ON PLAY(n) GOSUB Statement 


Specifies the first line number of a subroutine to be executed when 
the music buffer contains fewer than n notes. This permits con¬ 
tinuous background music during program execution. 

The ON PLAY(n) GOSUB statement is only used in a program. 


ON PLAY( n ) GOSUB linenum 











Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression in the range 1 to 32. Values 
outside this range result in an ’’Illegal function call” 


error. 

linenum 

Is the first line number of the associated trap 
routine. A line number of 0 disables play trapping. 


To Enable or Disable PLAY(n) Trapping 


IF... 

THEN... 

a PLAY ON is 
executed 

PLAY(n) trapping will be enabled. 

a PLAY OFF is 
executed 

PLAY(n) trapping will be disabled. 

a PLAY STOP is 
executed 

PLAY(n) trapping will be suspended, i.e. should the 
music buffer contain less than the specified number 
of notes, the GOSUB is not performed, but it will 
be performed as soon as a PLAY ON is executed. 

an ON PLAY(n) 

GOSUB is executed 

PLAY(n) trapping will be suspended. 

an error trap occurs 

all trapping will be disabled. 
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To Activate a PLAY(n) Trapping Routine 


IF... 

THEN... 

PLAY(n) trapping is 
enabled, and the 
background music 
buffer has gone from 
n to n-1 notes 

ON PLAY(n) GOSUB line will be executed, and the 
corresponding routine activated. To avoid recursive 
traps, a PLAY STOP is automatically executed 
when the trap occurs. A RETURN from the trapp¬ 
ing subroutine will automatically perform a PLAY(n) 
ON (unless a PLAY(n) OFF statement was perform¬ 
ed within the trap routine). The RETURN linenum 
form may also be used. Use this form with care, 
because any other active GOSUB, WHILE, or FOR 
statements will remain active, and errors (such as 
’’FOR without NEXT”) may result. 

the program is runn¬ 
ing, PLAY(n) trapping 
is enabled, and the 
background music 
buffer is empty 

no PLAY(n) trapping routine will be executed 


Remarks 

1. A PLAY event trap is only effective when playing Background 
Music (PLAY PLAY event traps have no effect when run¬ 

ning in Music Foreground (PLAY ”MF...”). 


2. A PLAY event trap is ineffective if the Music Background buffer 
is already empty when a PLAY ON is executed. 











3. Care should be taken in selecting values for n. If n is a large 
number, event traps will occur frequently enough to reduce pro¬ 
gram execution speed. 


Example 

10 PLAY ON 

20 ON PLAY(8) GOSUB 1000 


1000 ’SUB PLAY(8) TRAP 

1050 RETURN 


ON TIMER (n) GOSUB Statement 


Causes an event trap every n seconds. 

The ON TIMER (n) GOSUB statement is only used in a program. 


ON TIMER( n ) GOSUB linenum 
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Where 

SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression in the range 1 through 
86400 (1 second through 24 hours). Values outside 
this range will result in an ’’Illegal function call” 
error. 

linenum 

Is the entry point line number of the TIMER event 
trap subroutine. 


Characteristics 

The ON TIMER GOSUB statement will only be executed if a TIMER 
ON statement has been executed to enable event trapping. If event 
trapping is enabled, and if linenum in the ON TIMER GOSUB state¬ 
ment is not zero, GW-BASIC checks between statements to see if the 
time has been reached. If it has, a GOSUB will be performed to the 
specified line. 

If a TIMER OFF statement has been executed the GOSUB is not per¬ 
formed and is not remembered. 

If a TIMER STOP statement has been executed the GOSUB is not per¬ 
formed, but will be performed as soon as a TIMER ON statement is 
executed. 

If an ON TIMER(n) GOSUB is performed, an automatic TIMER STOP 
is executed so that recursive traps cannot take place. The RETURN 
from the trapping subroutine will automatically perform a TIMER ON 
statement unless a TIMER OFF statement was performed inside the 
subroutine. 











The RETURN linenum form of the RETURN statement may be us¬ 
ed to return to a specific line number from the trapping subroutine. 
Use this type of return with care, however, because any other GOSUBs, 
WHILES, or FORs that were active at the time of the trap will remain 
active, and errors such as ’’FOR without NEXT” may result. 


Example 

To display the time of day on line 1 every minute: 

10 ON TIMER (60) GOSUB 1000 
20 TIMER ON 


1000 OLDROW = CSRLIN ’ save current row 
1010 OLDCOL = POS(O) ’ save current column 
1020 LOCATE 1,1 : PRINT TIME$ 

1030 LOCATE OLDROW, OLDCOL ’restore row and column 
1040 RETURN 


OPEN Statement 


Allows I/O to a file or device. OPEN is usually used in a program. 
Syntax 1 


OPEN {device | filespec\pathname] [ FOR mode1][access] AS [# ] 
filenum [ LEN= record-length ] 
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Syntax 2 


OPEN mode2 , [#] filenum ,[filespec\ pathname}] , record-length] 


Where 


SYNTAX ELEMENT 

MEANING 

device 

Is a string expression which specifies the device 
to be opened 

filespec 

Is a string expression which specifies the file to be 
opened. It may optionally include a device. 

pathname 

Is a string expression which specifies the file to be 
opened. It may optionally include a device. 

model 

Is a literal string not enclosed in quotation marks. 

It determines the initial file pointer position and the 
action to be taken if the file does not exist. The valid 
modes and actions taken are: 

INPUT: specifies sequential input mode. Posi¬ 

tions the pointer to the beginning of an 
existing file. A ’’File not found” error is 
given if the file does not exist. 

OUTPUT: specifies sequential output mode. Posi¬ 
tions the pointer to the beginning of the 
file. If the file does not exist, one is 
created. 

► 
















SYNTAX ELEMENT 


access 


MEANING 


APPEND: specifies sequential output after the last 
record on the file. Positions the pointer 
to the end of the file. If the file does not 
exist, one is created. 

This mode is valid only for disk files. 

If the FOR model clause is omitted, the initial posi¬ 
tion is at the beginning of the file. If the file is not 
found, one is created in Random I/O mode (that 
is, records may be read or written, at will, at any 
position within the file). 


This parameter is used with systems that have MS- 
NET installed (MS-DOS releases 3.1 or later) and 
it specifies the access rights associated with the 
file specified. It can be one of the following: 

SHARED Any process on any 

machine may read or write 
the file. 

LOCK READ No other process is to be 

granted read access to this 
file. This access will be 
granted only if no other pro¬ 
cess has LOCK READ ac¬ 
cess to the file. 

LOCK WRITE No other process is to be 

granted write access to this 
file. This access will be 
granted only if no other pro¬ 
cess has LOCK WRITE ac¬ 
cess to the file. 

LOCK READ WRITE No other process is to be 
granted read or write access 
to this file. This access will 
be granted only if no other 
process has LOCK READ or 
WRITE access to the file. 

If access is not specified, the file may be opened 
for reading and writing any number of times by the 
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Cr SYNTAX ELEMENT 

MEANING 


process, but other processes are denied access to 
this file while it is open. See also the LOCK and 
UNLOCK statements. 

Note that if you try and use this parameter with an 
MS-DOS release prior to 3.1 you will get an “Ad¬ 
vanced Feature Error”. If you are using MS-DOS 
3.1 or later, but MS-NET is not installed, you will 
get a “Permission Denied”. The MS-DOS com¬ 
mand SHARE must also be given (either at the MS- 
DOS prompt or from an AUTOEXEC.BAT file). See 
the “MS-DOS User Guide” for a full description of 
procedures to be followed for networking. 

filenum 

• 

Is an integer expression returning a number in the 
range 1 through 255. The number is used to 
associate an I/O buffer with a disk file or device. 
This association exists until a CLOSE or CLOSE 
filenum statement is executed. The file is referred 
to by this number in any I/O statement by this 
number. 

record-length 

Is an integer expression from 1 to 32767. This value 
sets the record length to be used for random files. 
If omitted, the record-length defaults to 128 byte 
records. The record-length may not be greater than 
the value specified by the /S: switch in the 
GWBASIC command. GW-BASIC will ignore this 
option if it is used to OPEN a sequential file. 

mode2 

• 

Is a string expression whose first character is one 
of the following: 

0 Specifies sequential output mode 

1 Specifies sequential input mode 

R Specifies random input/output mode 

A Specifies sequential output mode and sets the 
file pointer at the end of the file, and the record 
number as the last record of the file. A PRINT# 
or WRITE # statement will then extend (append) 
the file. 















Characteristics 


A disk file must be opened before any disk I/O operation can be per¬ 
formed on that file. OPEN allocates a buffer for I/O to the file or device 
and determines the mode of access that will be used with the buffer. 
The filenum parameter specifies the number which will be associated 
with the file as long as it is open and will be used by other I/O 
statements to refer to the file or device. 

The maximum number of files that may be open simultaneously is set 
by the /F: switch in the GWBASIC command. This number falls within 
the range 1 to 15, and defaults to 3. 

For each device or file, the following OPEN modes are allowed: 

KYBD: INPUT only 

SCRN: OUTPUT only 

LPT1: OUTPUT or random (*) 

LPT2: OUTPUT or random (*) 

LPT3: OUTPUT or random (*) 

COM1:, COM2:, INPUT or OUTPUT 

Disk files INPUT, OUTPUT, APPEND or random 

(*) GW-BASIC will not send a line feed after each carriage return, if 

a printer has been opened in random mode with a width of 255. 

The GW-BASIC file I/O system allows the user to take advantage of 
user installed devices. 

Character devices are opened and used in the same manner as disk 
files. However, characters are not buffered by GW-BASIC as they are 
for disk files. The record length is set to one. 

GW-BASIC only sends a CR (carriage return X’OD’) as end of line. 
If the device requires a LF (line feed X’OA’), the driver must provide 
it. When writing device drivers, keep in mind that GW-BASIC users 
will want to read and write control information. Writing and reading 
of device control data is handled by the GW-BASIC IOCTL statement 
and IOCTL$(/) function. 
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Remarks 

1. If you enter a value outside of the corresponding range an ’’Illegal 
function call” error is returned, and the file will not be opened. 

2. If the file is opened for INPUT, attempts to write to the file will result 
in a ’’Bad file mode” error. If a file opened for input does not ex¬ 
ist, a ’’File not found” error occurs. 

3. When a disk file is opened for APPEND, the pointer position is 
initially at the end of the file and the record is set to the last record 
of the file. PRINT#, or WRITE# will then extend the file. 

4. If the file is opened for OUTPUT or APPEND, attempts to read 
the file will result in a ’’Bad file mode” error. 

5. If you open a file which does not exist for output, append, or ran¬ 
dom access, you will create that file. 

6. A file can be opened for sequential input or random access on 
more than one file number at a time. A file may NOT be opened 
for OUTPUT or APPEND, on more than one file number at a time. 

Moreover, since it is possible to reference the same file in a sub¬ 
directory via different pathnames, it is impossible for GW-BASIC 
to know that it is the same file simply by looking at the pathname. 
For this reason, GW-BASIC will not let you open the file for OUT¬ 
PUT or APPEND if it is on the same disk, even if the pathname 
is different. 


Examples 

10 OPEN ”I”,2,”INVEN” 

10 OPEN ’’MAILING.DAT” FOR APPEND AS 1 
10 OPEN ”CON:” FOR INPUT LOCK READ AS #1 
10 OPEN ’’MYFILE” FOR OUTPUT LOCK WRITE AS #2 








If you write and install a device called F01, then the OPEN statement 
might appear as: 


10 OPEN ”\DEV\F01” FOR OUTPUT AS #1 
To open the printer for output, the user could use the line: 

100 OPEN ”LPT:” FOR OUTPUT AS #1 
which uses the GW-BASIC device driver, or as part of a pathname as in: 

100 OPEN ”\DEV\LPT1 ” FOR OUTPUT AS #1 
which uses the MS-DOS device driver. 

Examples 

Using the following tree structure: 


ROOT 


/ \ 


ACCOUNTS 


SALES 




STEVE SUE 


JOHN MARY 



/ i 


ROBERT REPORT 


REPORT 


other 

files 


other 

files 


If MARY is your current directory, then: 

OPEN ’’REPORT”... 

OPEN ”\SALES\MARY\REPORT”... 
OPEN ”..\MARY\REPORT”... 

all refer to the same file. 
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Possible Errors 

’’Bad file name” 

’’Bad file number” 

’’Bad file mode” 

’’Too many files”: too many files are open. (See the /F: switch in the 
GWBASIC command line). 

’’File not found”: if a file opened for input does not exist. 

’’Device not available”: you have attempted to open either a direc¬ 
tory, or a non-existent device. 

’’File already open” 

’’Device I/O error”: reception error. Usually caused by an incorrectly 
written device driver (user-installed). 

’’Illegal function call”: usually caused by an excessive record length. 
(See the IS: switch in the GWBASIC command line). 

’’Permission Denied”: failed attempt to open a file, due to restriction 
of access. 

’’Path/File Access Error”: failed attempt to open a file, due to mode 
specified being incompatible with network-installed sharing access to 
a device. 






—' OPEN COM Statement 


Opens and initializes an RS-232-C port for input/output. 


OPEN ’’COM n : [speed] [ , [parity ][ , [data][ , [stop] [,RS][,CS [t]] 

[ ,DS [t]][ ,CD [f]][ ,BIN ][ ,ASC ][ ,LF ]]]]” [ FOR mode ] AS [ # ] filenum 
[ LEN = record-length] 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is 1 or 2. It specifies the number of the RS-232-C 
port. 

speed 

Is an integer constant which sets the baud rate in 
bits per second of the specified port. Valid values 
are: 75, 110, 150, 300, 600, 1200, 1800, 2400, 
4800, and 9600. The default value is 300 bps. 

parity 

Designates the parity. Valid entries are: 

E (even) - default value 

M (mark) 

N (none) 
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SYNTAX ELEMENT 

MEANING 


0 (odd) 

S (space) 

data 

Designates the number of data bits per byte. Valid 
entries are: 5, 6, 7 (default), or 8. 

stop 

Designates the stop bit. Valid entries are: 1, 1.5, 
or 2. If omitted then 75 and 110 bps transmit two 
stop bits, all others transmit one stop bit. 

RS 

Suppresses RTS (Request To Send) 

CS [t] 

Controls CTS (Clear To Send) 

DS [t] 

Controls DSR (Date Set Ready) 

CD [t] 

Controls CD (Carrier Detect) 

BIN 

Opens the file in binary mode. BIN is selected by 
default, unless ASC is specified. 

ASC 

Opens the file in ASCII mode. 

LF 

Specifies that a linefeed is to be sent after a car¬ 
riage return. 




















SYNTAX ELEMENT 

MEANING 


mode 

Is one of the following string expressions: 

OUTPUT Specifies sequential output mode 

INPUT Specifies sequential input mode 

If the mode expression is omitted, it is assumed to 
be random input/output. Random cannot, however, 
be explicitly chosen as mode. 

filenum 

Is the number of the file to be opened. 


record-length 

Is the length of the records written to or read from 
a communications buffer. This value cannot be 
greater than the value fixed by the /C: switch in the 
GWBASIC command. The default record-length for 
the receive buffer is 2 bytes. The length of the 
transmit buffer is 128 bytes. 


Characteristics 

The OPEN COM statement must be executed before an RS-232-C port 
can be used. 

Any syntax errors in the OPEN COM statement will result in a ’’Bad 
file name” error message. 

The speed, parity, data, and stop options must be 
listed in the order shown in the above syntax. The remaining options 
may be listed in any order, but they must be listed after the speed , 
parity , data , and stop options. 
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The CS, DS, and CD options allow you to specify a time ( t ) to wait for 
the signal before a ’’Device Timeout” error is returned. This time is 
expressed in milliseconds, ranging from 0 to 65535. Default values 
are: CD = 0, CS = 1000, DS = 1000. 

LF allows communication files to be printed on a serial line printer. 
When LF is specified, a linefeed character (OAH) is automatically sent 
after each carriage return character (ODH). This includes the carriage 
return sent as a result of the width setting. Note that INPUT# and LINE 
INPUT#, when used to read from a COM file that was opened with 
the LF option, stop when they see a carriage return, ignoring the 
linefeed. 

The LF option is superseded by the BIN option. 

In the BIN mode, tabs are not expanded to spaces, a carriage return 
is not forced at the end-of-line, and CTRL Z is not treated as end-of- 
file. When the file is closed, CTRL Z will not be sent over the RS-232 
line. The BIN option supersedes the LF option. 

In ASC mode, tabs are expanded, carriage returns are forced at the 
end-of-line, CTRL Z is treated as end-of-file, and XON/XOFF protocol 
is enabled. When the channel is closed, CTRL Z will be sent over the 
RS-232 line. 


Example 

10 OPEN ”COM1:9600,N,8,1 ,BIN” AS #2 

will open communications port 1 in random mode at a speed of 9600 
baud with no parity bit, 8 data bits, and 1 stop bit. Input/Output will 
be in binary mode. Other lines in the program may now access port 
1 as file number 2. 







OPTION BASE Statement 


Defines the minimum value for array subscripts. 


OPTION BASE n 


Where 


SYNTAX ELEMENT 

MEANING 

/ 

n 

Is an integer expression and may be 1 or 0 

Characteristics 

The default base is 0. 

, If the statement: 



OPTION BASE 1 


is executed, the lowest value an array subscript may have is 1. 


A CHAINed program may have an OPTION BASE statement if no ar¬ 
rays are passed. The CHAINed program will inherit the OPTION BASE 
value of the chaining program. 
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Possible Errors 

The OPTION BASE statement must be executed before definition or 
usage of arrays. A ’’Duplicate Definition” error occurs when the base 
value is changed when arrays are in existence. 


OUT Statement- 


Transmits a byte to an output port. 


OUT port, byte 


Where 


SYNTAX ELEMENT 

MEANING 

port 

Is an integer expression in the range 0 through 
65535 and represents an output port number. 

byte 

Is an integer expression in the range 0 through 255 
and represents the data to be transmitted. 

Characteristics 


OUT is the complimentary statement to the INP statement. 

If port or byte is outside the specified range, an’’Illegal func¬ 
tion call” error is returned. 













Example 


100 OUT 1234,255 


PAINT Statement 


Fills a graphics area with a color or a specified pattern (Graphics Mode 
only). 


PAINT [ STEP ] ( x , y) [ , [ paint ] [ , [border] [ , background ]]] 


Where 


SYNTAX ELEMENT 

MEANING 


*,y 

Are the coordinates, either absolute or relative, of 
a point where painting is to begin. Painting should 
always start on a non-border point. If painting starts 
within the border, the bordered figure is painted. 
If painting starts outside the bordered figure, the 
area outside the figure is painted to the extent of 
the current viewport. 

paint 

Is a numeric or string expression. If it is a numeric 
expression it must be in the range 0 to 3, and it 
represents the color number to be used for pain¬ 
ting. In Medium Resolution, paint selects the color 
from the active palette; in High and Super Resolu¬ 
tion, the values 0 and 2 indicate black, and 1 and 
3 indicate white. If paint is a string expression the 
area will be painted with a color pattern (tiling) as 
described later. If paint is not specified the default 
graphics foreground color is assumed. 
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SYNTAX ELEMENT 

MEANING 

border 

Is an integer expression in the range 0 to 3. It iden¬ 
tifies the border color of the figure to be filled. In 
Medium Resolution border selects the color from 
the active palette; in High and Super Resolution, 
the values 0 and 2 indicate black, and 1 and 3 in¬ 
dicate white. At the start of painting, the border 
must already have the specified color; when a pix¬ 
el of the border color is encountered, painting in 
this direction will stop. If border is omitted, the paint 
value will be assumed. 

background 

Is a string expression returning one character, us¬ 
ed to overcome the stop condition for painting when 
the paint parameter has a string value (see 
“Tiling”). 


Characteristics 

The PAINT statement will fill a figure, with edges of border color, with 
the specified paint color. 

For example, in Medium Resolution you can fill in a circle of border 
color number 1, with color number 2. Visually, this could mean a red 
circle with a green border (if palette 0 has been selected). 

Since there are only two colors in High Resolution and Super Resolu¬ 
tion, the PAINT statement can be used for ’’whiting out” an area until 
white is encountered, or ’’blacking out” an area until black is en¬ 
countered. 













PAINT must start on a non-border point, otherwise it will have no ef¬ 
fect. Nor will it have any effect if the specified point already has the 
border color. 

PAINT can fill any figure, but PAINTing complex figures may result 
in an ’’Out of Memory” error. If this happens, use the CLEAR state¬ 
ment to increase the amount of stack space available, and re-execute 
the program. 


Tiling 

Using the PAINT statement you can paint an area using various col¬ 
ors for the pixels, in order to achieve a “structure of colors” (or tiling). 
In order to use this feature, you must provide a string value for the 
paint parameter, according to the following syntax: 


PAINT( x ,y), CHR$ ( n ) [ + CHR$( n )]... 


where n is a number between 0 and 255, or between &H00 and &HFF 
in hexadecimal. You can specify up to 64 CHR$ (n) functions in each 
PAINT statement. The sequence of CHR$ (n) string functions allows 
you to create a mask (or “tiling patch”) with a rectangular structure 
of 8 bits in width and a variable height (up to 64 bits). This mask 
defines the basic tiling structure. 

The mask (which is repeated uniformly over the area to be painted 
and clipped at the borders of the area) is as follows: 


X —* 



y xxxxxxxx 

CHR$ (n) 

byte 0 

J xxxxxxxx 
xxxxxxxx 

CHR$ (n) 

byte 1 

CHR$ (n) 

byte 2 

xxxxxxxx 

CHR$ (n) 

byte 63 (maximum permitted) 
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The horizontal repetition of the mask on the screen is carried out in 
such a way that each line of the mask corresponds with one byte of 
the screen memory, that is 4 pixels in Medium Resolution and 8 pix¬ 
els in High and Super Resolution. Since there are 80 bytes associated 
with the entire screen, there are 80 possible horizontal positions that 
the mask can take. Vertically, the mask starts at the top margin of the 
screen and is repeated towards the bottom margin of the screen. This 
means that a mask of height h is repeated vertically every h scanlines, 
where the first line of the mask of always placed on a scanline (y- 
coordinate) that is a multiple of h. 

In order to calculate which line of the mask corresponds with a given 
scanline you must use the following formula: 


line = scanline MOD h 

Where 


line is the line of the mask; 0 is the topmost line 
scanline is the scanline (y-coordinate); 0 is the first scanline 
h is the height of the mask 

Using the following statement: 

PAINT (320, 100) , CHR$ (&H81) + CHR$ (&H42) + CHR$ 
(&H24) + CHRS (&H18) + CHR$ (&H18) + CHR$ 
(&H24) + CHR$ (&H42) + CHR$ (&H81) 

tiling begins at the point (320, 100), and the first scanline of the mask 
used is line 4, since line = 100 MOD 8. 


Using the above statement you can tile the screen with x’s, in High 
and Super Resolution; the mask is constructed as follows: 


x— 


1 

0 

0 

0 

0 

0 

0 

1 

0 

1 

0 

0 

0 

0 

1 

0 

0 

0 

1 

0 

0 

1 

0 

0 

0 

0 

0 

1 

1 

0 

0 

0 

0 

0 

0 

1 

1 

0 

0 

0 

0 

0 

1 

0 

0 

1 

0 

0 

0 

1 

0 

0 

0 

0 

1 

0 

1 

0 

0 

0 

0 

0 

0 

1 


CHR$ (&H81) byte 0 
CHR$ (&H42) byte 1 
CHR$ (&H24) byte 2 
CHR$ (&H18) byte 3 
CHR$ (&H18) byte 4 
CHR$ (&H24) byte 5 
CHR$ (&H42) byte 6 
CHR$ (&H81) byte 7 


The same PAINT statement, in Medium Resolution, paints the screen 
with a red and green pixel pattern (if the active palette is palette 0). 






In some cases you may want to tile a figure which is already painted; 
if the area of the figure being tiled has the same color as two con¬ 
secutive characters in the mask, tiling will be terminated. It is possible 
to overcome this limitation by using the background parameter; in order 
to specify that a color should not be considered as a stop condition, 
you have to assign to background the value of the two consecutive 
mask characters. If palette 0 was active for example, and you had 
assigned CHR$ (&HAA) to background (that is red), it would be possi¬ 
ble to draw two red lines and two blue lines, alternatively, onto a 
background color of red. 

If you specify more than two consecutive bytes in the mask that match 
background you will get the error message “Illegal function call’’; this 
means that it is not possible to draw, for example, more than two red 
lines on an area already painted red. 


Example 

10 SCREEN 1 
20 COLOR 0,0,1,0 
30 CLS 

40 CIRCLE (256,128), 130,2 

50 PAINT (256,128),1,2 

60 LINE (251,123)-STEP(10,10),0,BF 

Statement 10 selects Medium Resolution. Statement 20 selects black 
for color number 0, palette 0 (green, red, yellow), green as graphics 
foreground, black as graphics background. Statement 30 clears the 
screen with the background color (in this case black). Statement 40 
draws a red circumference with a radius of 130 whose center is 
(256,128). Statement 50 paints the circle green. Statement 60 draws 
a black filled-in box in the middle of the circle. 
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PEEK Function 

Returns the byte read from the specified memory location. 


PEEK( offset) 


Where 


SYNTAX ELEMENT 

MEANING 

offset 

Is a numeric expression returning an integer in the 
range 0 to 65535. It indicates the address of the 
memory location of the byte that PEEK will read. 

It is the offset from the current segment, which was 
defined by the last DEF SEG statement (if no DEF 

SEG statement has been executed the current seg¬ 
ment is the GW-BASIC Data Segment). 


Characteristics 

The returned value is an integer in the range 0 to 255. 

If offset is outside the specified range, an ’’Illegal function call” 
error is returned. 

PEEK is the complementary function of the POKE statement. 

Example 


A = PEEK(&H5A00) 















PLAY Statement 


Plays music in accordance with a string which specifies the notes to 
be played, and the way in which the notes are to be played. 


PLAY stringexp 


Where 


SYNTAX ELEMENT 

MEANING 

stringexp 

Is a string expression containing a series of single¬ 
character commands 

Characteristics 


PLAY uses a concept similar to that in DRAW by embedding a Music 
Macro Language into one statement. A set of subcommands, used as 
part of the PLAY statement, specifies the particular action to be taken. 
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The subcommands used for stringexp are: 


COMMAND 

ACTION 

A-G[ # | + | -] 

Plays a note in the range A-G. The suffixes (#) or 
(+) after the note specify sharp; suffix (-) specifies 
flat. 

On 

Sets the current octave. There are seven octaves, 
numbered 0 through 6. 

>n 

Increments the octave and plays note n. The oc¬ 
tave is progressively incremented, each time note 
n is played, until octave 6 is reached. Note n is 
subsequently played at octave 6. 

<n 

Decrements the octave and plays note n. The oc¬ 
tave is progressively decremented, each time note 
n is played, until octave 0 is reached. Note n is 
subsequently played at octave 0. 

N n 

Plays one of 84 notes within the 7 possible octaves. 
The n parameter ranges from 0 to 84; 0 indicates 
a rest. This command is an alternative to specify¬ 
ing notes using the note name (A-G) and octave 
number commands. 

P n 

Specifies a pause. The n parameter ranges from 
1 to 64 and corresponds to the length of each note, 
set by L/7. 




















COMMAND 

ACTION 

Ln 

Sets the length of each note. The n parameter 
ranges from 1 to 64, where n = 1 is equivalent to 
a whole note; n = 4 is equivalent to a quarter note, 
etc. 


The length may also follow the note when a change 
of length only Is required for a particular note. In 
this case, A16 is equivalent to L16A. 


A period after a note causes the note to be played 
3/2 times the length determined by L multiplied by 
T (tempo). Multiple periods may appear after a note. 
The period is scaled accordingly; e.g., A. is 3/2, A., 
is 9/4, A... is 27/8, etc. Periods may appear after 
a pause (P). In this case, the pause length may be 
scaled in the same way notes are scaled. 

T n 

Sets the tempo, or number of quarter notes in one 
minute. The n parameter ranges from 32 to 255, 
with a default value of 120. 

MF 

Sets Music Foreground. The PLAY and SOUND 
statement are to run in foreground. Each suc¬ 
cessive note or sound will not start until, the 
preceding note or sound has finished. This is the 
default setting. 

MB 

Sets Music Background. The PLAY and SOUND 
statement are to run in background. That is, each 
note or sound is placed in a buffer allowing the GW- 
BASIC program to continue executing while the 
note or sound plays in the ’’background”. Up to 
32 notes can be played in the background at a time. 
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COMMAND 

ACTION 

MN 

Sets ’’music normal”, so that each note will play 
7/8 of the time determined by length (L). 

ML 

Sets ’’music legato”, so that each note will play the 
full period set by length (L). 

MS 

Sets ’’music staccato”, so that each note will play 
3/4 of the time set by length (L). 

X string 

Executes the specified string. 


Remarks 


The n parameter may be constant or variable, where a variable 
is written as = variable;. The semicolon is necessary when a 
variable is used in this way, or when the X command is used, but it 
is not allowed after MF, MB, MN, ML, or MS. In all other cases, a 
semicolon is optional between commands. 


Example 

10 LET LISTEN$ = ”T180 02 P2 P8 L8 GGG L2 E-” 
20 LET FATE$ = ”P24 P8 L8 FFF L2 D” 

30 PLAY LISTENS + FATES 


This example will play the beginning 
Beethoven’s Fifth Symphony. 


of the first movement of 
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Examples 

100 PLAY ”< <” ’Decrement by two octaves 

200 PLAY ”>” ’Increment by an octave 

300 PLAY ”A>” ’Increment by an octave and play an A note 

400 PLAY ”XSONG$” 


PLAY(n) Function 


Returns the number of notes remaining in the music background buffer. 


PLAY( n ) 


Where 


SYNTAX ELEMENT 

MEANING 


n 

Is a dummy argument. Any value may be supplied. 
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Characteristics 


IF... 

THEN 

The program is 
running in Music 
Foreground mode 

PLAY(n) returns 0 

The program is 
running in Music 
Background mode 

PLAY(n) returns the number of notes currently in 
the Music Background buffer. The maximum value 
that PLAY(n) may return is 32. 

Example 


10 IF PLAY(O) = 6 GOTO 500 


PLAY ( ON | OFF | STOP ) Statements 


PLAY ON enables PLAY(n) trapping. 
PLAY OFF disables PLAY(n) trapping. 
PLAY STOP suspends PLAY(n) trapping. 


PLAY { ON | OFF | STOP ] 
















Characteristics 

PLAY ON, PLAY OFF, PLAY STOP are used in conjunction with the 
ON PLAY(n) GOSUB statement. 

If a PLAY OFF statement has been executed the GOSUB is not per¬ 
formed and is not remembered. 

If a PLAY STOP statement has been executed the GOSUB is not per¬ 
formed, but will be performed as soon as PLAY ON statement is ex¬ 
ecuted. 

If an ON PLAY(n) GOSUB is performed, an automatic PLAY STOP 
is executed. 

Once an error trap takes place, all trapping is automatically disabled. 

The RETURN linenum form of the RETURN statement may be us¬ 
ed to return to a specific line number from the trapping subroutine. 
Use this type of return with care, however, because any other GOSUBs, 
WHILES, or FORs that were active at the time of the trap will remain 
active, and errors such as ’’FOR without NEXT” may result. 


PMAP Function 


Converts screen coordinates to world coordinates or vice versa. 
(Graphics Mode only). 


PMAP( coordinate , n ) 
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Where 


SYNTAX ELEMENT 

MEANING 

coordinate 

Is a numeric expression specifying either the x 
coordinate or the y coordinate of the point to be 
mapped according to the value of n. 

n 

Is an integer number in the range 0 to 3: 

0 specifies that the coordinate value is the world 
x coordinate, which is to be mapped to the screen 
x coordinate 

1 specifies that the coordinate value is the world 
y coordinate, which is to be mapped to the screen 
y coordinate 

2 specifies that the coordinate value is the screen 
x coordinate, which is to be mapped to the world 
x coordinate 

3 specifies that the coordinate value is the screen 
y coordinate, which is to be mapped to the world 
y coordinate 


Characteristics 

The four PMAP functions allow you to find equivalent point locations 
between those in the window created with the WINDOW statement and 
those in the viewport as defined by the VIEW statement. 














Examples 

If a user had defined a WINDOW SCREEN (80,100) - (200,200) then 
the upper left coordinate of the window would be (80,100) and the lower 
right would be (200,200). With screen2 the coordinates are (0,0) in the 
upper left hand corner and (639,199) in the lower right. Then: 

X = PMAP(80,0) 

would return the screen x coordinate that corresponds to the world 
x coordinate 80: 

0 

The PMAP function in the statement: 

Y = PMAP(200,1) 

would return the screen y coordinate that corresponds to the world 
y coordinate 200: 

199 

The PMAP function in the statement: 

X = PMAP(639,2) 

would return the world x coordinate that corresponds to the screen 
x coordinate 639: 

200 

The PMAP function in the statement: 

Y = PMAP(199,3) 

would return the world y coordinate that corresponds to the screen 
y coordinate 199: 

200 
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POINT Function 


Returns the color number of a pixel on the screen, if two arguments 
\x,y) are given, or the x- or y-coordinate of the last referenced point 
if one argument (n) is given (Graphics Mode only). 

Syntax 1 


POINT( x , y ) 


Syntax 2 


POINT( n ) 


Where 


SYNTAX ELEMENT 

MEANING 

*,y 

Are the absolute screen coordinates of the selected 
pixel. If the point is outside the current viewport, 
the value -1 is returned. 
















SYNTAX ELEMENT 


MEANING 


n 


May have the following values: 


0 Specifies the current screen x coordinate 

1 Specifies the current screen y coordinate 

2 Specifies the current world x coordinate if a WIN¬ 
DOW statement has been executed, otherwise 
specifies the same value as the POINT(O). 

3 Specifies current world y coordinate if a WIN¬ 
DOW statement has been executed, otherwise 
specifies the same value as the POINT(I). 


Characteristics 

v% = POINT(x,y) 

returns the color number of the specified pixel into the integer variable 
v%. 

In Medium Resolution, POINT (x, y) can return 0, 1, 2 or 3; in High 
and Super Resolution, it can return 0 or 1. 

v2 = POINT(I) 

returns the screen coordinate of the current point into the single (or 
double) precision variable v2. 
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Example 

10 SCREEN 2 

20 IF POINT(l,l)< >0 THEN PRESET (1,1) ELSE PSET (1,1) 
30 ’Invert point for B/W system 
40 PSET (l,l),1-POINT(l,l) 


Example 

10 SCREEN 1 
20 LET C = 3 
30 PSET (10,10),C 

40 IF POINT(10,10) = C THEN PRINT ’’This point is color ”;C 









POKE Statement 


Writes a byte into a memory location. 


POKE offset, byte 


Where 


SYNTAX ELEMENT 

MEANING 


offset 

Is a numeric expression returning an integer in the 
range 0 to 65535 and indicates the address of the 
memory location where the byte is to be written by 
the POKE statement. It is the offset from the cur¬ 
rent segment, which was set by the last DEF SEG 
statement. If no DEF SEG statement has been ex¬ 
ecuted, the current segment is the GW-BASIC Data 
Segment. 

byte 

Is the byte to be written to the specified address. 
It must be in the range 0 to 255. 


Characteristics 

You can use POKE and PEEK for passing arguments and data to 
machine language subroutines. If either offset or byte is out¬ 
side the specified range, an ’’Illegal function call” error is returned. 
The complementary function to POKE is PEEK. 
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Warning 

Use POKE carefully. If it is used incorrectly, it can cause GW-BASIC 
or MS-DOS to crash. 

Example 

10 POKE &H5A00,&HFF 


POS Function 


Returns the current horizontal (column) position of the cursor. 


POS( dummy) 


Where 


SYNTAX ELEMENT 

MEANING 

dummy 

Is a dummy argument. Any value is accepted. 


Characteristics 

The current horizontal (column number) position of the cursor is return¬ 
ed. The leftmost position is 1. The rightmost position may be 40, or 
80, depending on the current screen width. To return the current ver¬ 
tical line position of the cursor (row number), use the CSRLIN function. 














Example 

IF POS(O) > 70 THEN BEEP 

• 

reen 

mi rritot i oiaiernent 

Draws or erases a point at the specified position on the sci 
(Graphics Mode only). 

PRESET [ STEP ] ( x , y ) [, color ] 


Where 

a 

SYNTAX ELEMENT 

MEANING 

IP 

De in 
is in- 

*,y 

Are the coordinates of the point. They may 1 
absolute or relative form (if the STEP option 
eluded) 

color 

Is an integer expression representing the color 
number of the specified point, in the range 0 to 3. 

In Medium Resolution color is chosen from the ac¬ 
tive palette; in High and Super Resolution, the 
values 0 and 2 indicate black and 1 and 3 indicate 
white. If no color parameter is given, the graphics 
background color is selected. If color is included, 

PRESET has the same meaning as PSET. 

• 
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Example 

PRESET (x,y) 

Erases the point at the given coordinates from the screen; it has the 
same meaning as: 

PSET (x,y),0 

if the graphics background color is 0. 

Possible Errors 

If a color greater than 3 is given this will result in an “Illegal function 
call”. 


PRINT Statement 


Outputs data to the screen. 


PRINT [list-of-expressions[ , | ; ]] 


Where 


SYNTAX ELEMENT 

MEANING 

list-of-expressions 

May be numeric and/or string expressions. (String 
constants must be enclosed in quotation marks.) 
Each expression should be separated from the next 
by a comma, blank, or semicolon. 













Characteristics 

If you omit the list-of-expressions, a blank line is displayed. If you in¬ 
clude the list-of-expressions, the values of the expressions are 
displayed on the screen. 

The position of each printed item is determined by the punctuation used 
to separate the items in the list. GW-BASIC divides the line into print 
zones of 14 spaces each. In the list of expressions, a comma causes 
the next value to be printed at the beginning of the next zone. A 
semicolon causes the next value to be printed immediately after the 
last value. Typing one or more spaces between expressions has the 
same effect as typing a semicolon. 

If a comma or a semicolon terminates the list of expressions, the next 
PRINT or PRINT USING statement begins printing on the same line, 
spacing accordingly. If the list of expressions terminates without a com¬ 
ma or a semicolon, a carriage return is printed at the end of the line. 
If the printed line is longer than the terminal width, GW-BASIC goes 
to the next physical line and continues printing. 

Printed numbers are always followed by a space. Positive numbers 
are preceded by a space. Negative numbers are preceded by a minus 
sign. Single precision numbers that can be represented with 7 or fewer 
digits in the unsealed format, are output using the unsealed format. 
For example, 1E-7 is output as .0000001 and 1E-8 is output as 1E-08. 
Double precision numbers that can be represented with 16 or fewer 
digits in the unsealed format no less accurately than they can be 
represented in the scaled format, are output using the unsealed for¬ 
mat. For example, ID-16 is output as .00000000000000001 and ID-17 
is output as ID-17. 

A question mark may be used in place of the word PRINT in a PRINT 
statement. 
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Example 1 


10 X = 5 

20 PRINT X + 5,X-5,X*(-5),X a 5 
30 END 

RUN 

10 0 -25 3125 

Ok 

In this example, the commas in the PRINT statement cause each value 
to be printed at the beginning of the next print zone. 


Example 2 
LIST 

10 INPUT X 

20 PRINT X ’’SQUARED IS” Xa2 ’’AND”; 

30 PRINT X ’’CUBED IS” Xa3 

40 PRINT 

50 GOTO 10 

Ok 

RUN 

? 9 

9 SQUARED IS 81 AND 9 CUBED IS 729 

? 21 

21 SQUARED IS 441 AND 21 CUBED IS 9261 


? 


In this example, the semicolon at the end of line 20 causes both PRINT 
statements to be printed on the same line. Line 40 causes a blank line 
to be printed before the next prompt. 


Example 3 

10 FOR X = 1 TO 5 
20 J = J + 5 
30 K = K + 10 
40 ?J;K; 

50 NEXT X 







RUN 

5 10 10 20 15 30 20 40 25 50 
Ok 


In this example, the semicolons in the PRINT statement cause each 
value to be printed immediately after the preceding value; a number 
is always followed by a space, and positive numbers are preceded by 
a space. In line 40, a question mark is used instead of the word PRINT. 


= PRINT USING Statement 


Outputs data to the screen using a specified format. 


PRINT USING format-string ; list-of-expressions[ , \ ; ] 


Where 


SYNTAX ELEMENT 

MEANING 


format-string 

Is a string expression (usually a constant or 
variable) composed of special formatting 
characters. These formatting characters determine 
the field and the format of the printed strings or 
numbers. 

list-of-expressions 

Is comprised of the string expressions or numeric 
expressions that are to be printed, separated by 
semicolons, or commas. String constants must be 
enclosed in quotation marks. If a comma or a 
semicolon terminates the list of expressions, the 
next PRINT or PRINT USING statement begins 
printing on the same line, spacing accordingly. 
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String Fields 

When PRINT USING is used to print strings, one of three formatting 
characters may be used to format the string field: 


FORMATTING 

CHARACTER 

! 

MEANING 

Specifies that only the first character in the given 
string is to be printed. 

\n spaces\ 

Specifies that 2 + n characters from the string are 
to printed. If the backslashes are typed with no 
spaces, two characters will be printed; with one 
space, three characters will be printed, and so on. 

If the string is longer than the field, the extra 
characters are ignored. 

If the field is longer than the string, the string will 
be left-justified in the field and padded with spaces 
on the right. 

For example: 

10 A$ = ”LOOK”:B$ = ’’OUT” 

30 PRINT USING ”!”;A$;B$ 

40 PRINT USING ”\ \”;A$;B$ 

50 PRINT USING ”\ \”;A$;B$;”I!” 

RUN 

LO 

LOOKOUT 

LOOK OUT !! 













FORMATTING 

CHARACTER 

MEANING 

& 

Specifies a variable length string field. When the 
field is specified with the string is output 

without modification. 


For example: 


10 A$ = ”LOOK”:B$ = ”OUT M 

20 PRINT USING ”!”;A$; 

30 PRINT USING ”&”;B$ 

RUN 

LOUT 


Numeric Fields 

When PRINT USING is used to print numbers, the formatting special 
characters may be used to format the numeric field: 


FORMATTING 

CHARACTERS 

MEANING 

# 

Represents each digit position. Digit positions are 
always filled. If the number to be printed has fewer 
digits than positions specified, the number will be 
right-justified (preceded by spaces) in the field. 
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FORMATTING 

CHARACTER 

MEANING 


A decimal point may be inserted at any position in the 
field. If the format string specifies that a digit is to 
precede the decimal point, the digit will always be 
printed (as 0, if necessary). Numbers are rounded as 
necessary. 

PRINT USING ”# #.# #”;.78 

0.78 

PRINT USING "# # #.# #”;987.654 

987.65 

PRINT USING ”##.## ”;10.2,5.3,66.789,.234 

10.20 5.30 66.79 0.23 

In the last example, three spaces were inserted at the 
end of the format string to separate the printed values 
on the line. 

+ 

A plus sign at the beginning or end of the format string 
will cause the sign of the number (plus or minus) to 
be printed before or after the number. 


A minus sign at the end of the format field will cause 
negative numbers to be printed with a trailing minus 
sign. 

PRINT USING ”+##.## ”;-68.95,2.4,55.6,-.9 

-68.95 + 2.40 + 55.60 -0.90 

PRINT USING ”##.##- ”;-68.95,22.449,-7.01 

68.95- 22.45 7.01- 
















FORMATTING 

CHARACTER 

MEANING 

• 

* * 

A double asterisk at the beginning of the format string 
causes leading spaces in the numeric field to be fill¬ 
ed with asterisks. The * * also specifies positions for 
two more digits. 

PRINT USING ”**#.# ”;12.39,-0.9,765.1 

*12.4 *-0.9 765.1 

$$ 

A double dollar sign causes a dollar sign to be printed 
to the immediate left of the formatted number. The $$ 
specifies two more digit positions, one of which is the 
dollar sign. The exponential format cannot be used 
with $$. Negative numbers cannot be used unless the 
minus sign trails to the right. 

PRINT USING ”$$###.# #”;456.78 
$456.78 

**$ 

The * *$ at the beginning of a format string combines 
the effects of the above two symbols. Leading spaces 
will be asterisk-filled and a dollar sign will be printed 
before the number. * *$ specifies three more digit posi¬ 
tions, one of which is the dollar sign. 

PRINT USING ”**$##.# #”;2.34 
***$2.34 

► 


• 
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FORMATTING 

CHARACTER 

MEANING 

J 

A comma that is to the left of the decimal point in 
a formatting string causes a comma to be printed 
to the left of every third digit to the left of the decimal 
point. A comma that is at the end of the format 
string is printed as part of the string. A comma 
specifies another digit position. The comma has no 
effect if used with the exponential (a a a a) 
format. 

PRINT USING ”####,.## ”;1234.5 

1,234.50 

PRINT USING ”####.##, ”;1234.5 

1234.50, 

A A A A 

Four carets (or up-arrows) may be placed after the 
digit position characters to specify exponential for¬ 
mat. The four carets allow space for E + xx or D + xx 
to be printed. Any decimal point position may be 
specified. The significant digits are left-justified, and 
the exponent is adjusted. Unless a leading + or 
trailing + or - is specified, one digit position will 
be used to the left of the decimal point to print a 
space or a minus sign. 

PRINT USING ”##.##aaaa ”;234.56 

2.35E + 02 

PRINT USING ”.####aaaa -”;888888 

.8889E + 06 

PRINT USING ” + .## aaa a”;123 
+ .12E + 03 











FORMATTING 

CHARACTER 


MEANING 


An underscore in the format string causes the next 
character to be output as a literal character. 

PRINT USING ”_!##.##_!”; 12.34 
112.34! 

The literal character itself may be an underscore 
by placing in the format string. 


If the number to be printed is larger than the 
specified numeric field, a percent sign is printed 
in front of the number. If rounding causes the 
number to exceed the field, a percent sign will be 
printed in front of the rounded number. 

PRINT USING ”# #.# #”;111.22 

% 111.22 

PRINT USING ”.##”;.999 
%1.00 

If the number of digits specified exceeds 24, an ’’Il¬ 
legal function call” error will result. 
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PRINT# and PRINT# USING Statements 


Write data sequentially to a disk file. The PRINT # and PRINT # US¬ 
ING statements are usually used in a program. 


PRINT # filenum , [ USING format-string ; ]list-of-expressions 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the number used when the file was OPENed with 
the option OUTPUT specified 

format-string 

Is a string expression (usually a constant or 
variable) composed of formatting characters 
described in the ’’PRINT USING” statement 

list-of-expressions 

Is a list of the numeric and/or string expressions 
to be written to file 

Characteristics 


PRINT # does not compress data on the disk. An image of the data 
is written to the disk, just as it would be displayed on the terminal screen 
with a PRINT statement. For this reason, care should be taken to delimit 
the data on the disk, so that it will be input correctly from the disk. 
















In the list of expressions, numeric expressions should be delimited by 
semicolons. For example: 

50 PRINT #1,B;C;D;X;Y;Z 

(If commas are used as delimiters, the extra blanks that are inserted 
between print fields will also be written to the disk.) 

String expressions must be separated by semicolons in the list. To 
format the string expressions correctly on the disk, use explicit 
delimiters in the list of expressions. 


For example, let A$ = ’’CAMERA” and B$ = ”93604-1 ”. The statement 
100 PRINT#1,A$;B$ 

would write CAMERA93604-1 to the disk. Because there are no 
delimiters, this could not be input as two separate strings. To correct 
the problem, insert explicit delimiters into the PRINT # statement as 
follows: 

200 PRINT# 1,A$;”,”;B$ 

The image written to disk is: 

CAMERA,93604-1 

which can be read back into two string variables. If the strings 
themselves contain commas, semicolons, significant leading blanks, 
carriage returns, or line feeds, write them to disk surrounded by ex¬ 
plicit quotation marks, using CHR$(34). For example, let 
A$ =’’CAMERA, AUTOMATIC” and B$ = ” 93604-1”. The 

statement: 

300 PRINT# 1,A$;B$ 
would write the following image to disk: 

CAMERA, AUTOMATIC 93604-1 
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And the statement: 

400 INPUT #1,A$,B$ 

would input ’’CAMERA” to A$ and ’’AUTOMATIC 93604-1 ” to B$. 
To separate these strings properly on the disk, write double quotation 
marks to the disk image using CHR$(34). The statement: 

500 PRINT# 1 ,CHR$(34);A$;CHR$(34);CHR$(34);B$;CHR$(34) 

writes the following image to disk: 

’’CAMERA, AUTOMATIC”” 93604-1” 

And the statement: 

600 INPUT #1,A$,B$ 

would input ’’CAMERA, AUTOMATIC” to A$ and ” 93604-1” to 

B$. The PRINT # statement may also be used with the USING option 
to control the format of the disk file. For example: 


700 PRINT# 1 ,USING”$$###.##,”;J;K;L 

For more examples using PRINT#, see Chapter 4 (Disk File Handl¬ 
ing). See also ’’WRITE#”, later in this chapter. 



PSET [ STEP ] ( x , y ) [ , color ] 



















Where 


SYNTAX ELEMENT 

MEANING 

*,y 

Are the coordinates of the pixel to be illuminated. 

You may specify them either in absolute or relative 
form. 

color 

Is an integer expression whose value is in the range 

0 to 3. It represents the color number of the point 
specified. In Medium Resolution color in chosen 
from the active palette; in High and Super Resolu¬ 
tion the values 0 and 2 represent black and 1 and 

3 represent white. If color is not specified the 
graphics foreground color is selected. 


Characteristics 

Coordinates can be specified in one of two forms: 

PSET STEP ( x-offset, y-offset) or 
PSET ( absolute-x, absolute-y ) 

The first form is a point relative to the most recent point referenced. 
The second form is more common and directly refers to a point without 
regard to the last point referenced. 

Examples are: 

PSET (10,10) absolute form 

PSET STEP (10,0) offset 10 in x and 0 in y 


PSET (0,0) 

origin 
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Examples 

This example draws a diagonal line from (0,0) to (100,100): 

10 FORi=0 TO 100 
20 PSET (i,i) 

30 NEXT 


This example erases the line by setting each pixel to 0: 

40 FOR i = 100 TO 0 STEP -1 
50 PSET (i,i),0 
60 NEXT 


PUT (COM files) Statement == 


Writes a specified number of bytes to a communications file. PUT (COM 
files) is usually used in a program. 


PUT [ # ] filenum[ , length] 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is an integer expression returning a valid file 
number 

















SYNTAX ELEMENT 

MEANING 

• 

length 

Is an integer expression returning the number of 
bytes to be transferred out of the communications 
buffer, length cannot exceed the value specified 
by the LEN clause in the OPEN COM statement. 

Example 

100 PUT#2,80 

• 

?s) is 

=^= PUT (Files) Statement 

Writes a record from a random buffer to a random file. PUT (File 
usually used in a program. 

PUT [ # ]filenum[ , recordnum ] 


Where 


SYNTAX ELEMENT 

MEANING 


filenum 

Is the number under which the file was OPENed ^ 




8-274 


GW-BASIC INTERPRETER USER GUIDE 






















COMMANDS, STATEMENTS AND FUNCTIONS 


SYNTAX ELEMENT 

MEANING 

recordnum 

The number of the record in the file. It must be in 
the range 1 to 16,777,215. If omitted the current 
record number is assumed (i.e., the record whose 
number is one higher than that of the last record 
accessed). 

Characteristics 


PRINT#, PRINT# USING, WRITE #, LSET and RSET may be used 
to put characters in the random file buffer before executing a PUT 
statement. 

In the case of WRITE#, GW-BASIC pads the buffer with spaces up 
to the carriage return. 


Example 

LIST 

10 OPEN ”r”,1,”A:RAND”,48 
20 FIELD 1,20 AS R1$,20 AS R2$,8 AS R3$ 
30 FOR L = 1 TO 4 
40 INPUT ”name”;N$ 

50 INPUT ”address”;M$ 

60 INPUT ”phone”;P$ 

70 LSET R1$ = N$ 

80 LSET R2$ = M$ 

90 LSET R3$ = P$ 

100 PUT 1 ,L 
110 NEXT L 
120 CLOSE 1 
130 END 
Ok 










RUN 

name? super man 
address? USA 
phone? 11234621 
name? robin hood 
address? England 
phone? 23462101 


Ok 

Statement 10 opens the random file RAND, with a record length of 
48 on the diskette inserted in drive A. The file number is 1. Statement 
20 divides the buffer into fields. 

Statement 100 writes a record to file RAND, with the record number 
being set by the control variable of the FOR/NEXT loop. 


Possible Errors 

Any attempt to read or write past the end of the buffer causes a “Field 
overflow” error. 


= _ PUT (Graphics) Statement 


Transfers the graphics image stored in an array by a GET statement, 
to the screen. 


PUT ( x, y ), array[ , action-verb] 
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7 

Where 

SYNTAX ELEMENT 

MEANING 

*>y 

Represent the top left corner of the rectangle to be 
displayed 

array 

Is the name of an array containing the image to be 
displayed. The type of the array must be numeric. 

action-verb 

Is a string of characters that specify a logical opera¬ 
tion between the colors of the points to be displayed 
and the colors of the points already on the screen. 
The string can be one of the following: PSET, 
PRESET, AND, OR, XOR. The default action- verb 
is XOR. 


Remarks 

The PUT statement is used to transfer an image onto the screen, 
taking it from an array in memory (the image must have already been 
stored using a GET statement): it also allows the animation of objects. 

The array, which can be of any numeric type, holds the image, and 
must have been given dimensions large enough to hold the colors of 
all the pixels of the image. 


The Action Verb Parameter 

The action-verb specifies the logical operation to be carried out 
between the colors of points to be displayed and the colors of the pix¬ 
els already on the screen. 











It can have one of the following values: 

• PSET, transfers the data pixel by pixel onto the screen. Each pixel 
has the exact color it had when it was memorized from the screen. 

• PRESET, is the same as PSET except that a negative image is 
produced. 

• AND is used when the image is to be transferred over an existing 
image on the screen. Points that had the same color in both the ex¬ 
isting image and the image to be displayed will remain the same 
color, points that do not have the same color are transformed using 
the AND operation between corresponding bits. 

• OR, is used to superimpose the image onto an existing image. 

• XOR, is used for animation. It causes a point on the screen to be 
inverted if there is a corresponding point in the image stored in the 
array. When an image is displayed on a complex background twice 
in the same position, the image is erased without altering the 
background color. This allows you to move an object around the 
screen without altering the background colors. 

In Medium Resolution AND, OR and XOR have the following effects 

on color: 
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Animation 

The GET and PUT statements allows the animation of objects, through 
the use of the following procedure: 

1. PUT the image on the screen (with the XOR option) 

2. Calculate the new position of the rectangle that contains the image. 

3. PUT the image on the screen (with the XOR option) a second time 
at the old location to remove the old image 

4. Go to step 1, but this time PUT the image at the new location. 

Movement done this way will leave the background color unchanged. 
Flicker can be cut down by minimizing the time between steps 4 and 
1, and by making sure that there is enough time delay (using a 
FOR/NEXT delay loop, for example) between 1 and 3. If more than 
one object is being animated, every object should be processed at 
once, one step at a time. 

If it is not important to preserve the background color, animation can 
be performed using the PSET action-verb statement. The idea is to 
leave a border around the image when it is first displayed as large or 
larger than the maximum distance the object will move. Thus, when 
an object is moved, this border will effectively erase any points left 
by the previous PUT. This method may be somewhat faster than the 
method using XOR described above, since only one PUT is required 
to move an object (although you must PUT a larger image). 


Possible Errors 

An ’’Illegal function call” error occurs if the image to be transferred 
is too large to fit on the screen. 





RANDOMIZE Statement 


Reseeds the random number generator. 


RANDOMIZE [numexp] 


Where 


SYNTAX ELEMENT 

MEANING 


numexp 

Is any numeric expression. The value of the expres¬ 
sion will be used to seed the random numbers. 


Characteristics 

If numexp is omitted, GW-BASIC suspends program execution and 
asks for a value by displaying: 

Random Number Seed (-32768 to 32767)? 

before executing RANDOMIZE. 

To get a new random seed without prompting the user, use the numeric 
TIMER function. For example: 

RANDOMIZE TIMER 
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If the random number generator is not reseeded, the RND function 
returns the same sequence of random numbers each time the pro¬ 
gram is RUN. To change the sequence of random numbers every time 
the program is RUN, place a RANDOMIZE statement at the beginn¬ 
ing of the program and change the argument with each RUN. 


Example 

10 RANDOMIZE 
20 FOR I = 1 TO 5 
30 PRINT RND; 

40 NEXT I 

RUN 

Random Number Seed (-32768 to 32767)? 3 
.2226007 .594141419 .2414202 .2013798 5.361748E-02 
Ok 

RUN 

Random Number Seed (-32768 to 32767)? 4 
.628988 765605 .5551561 .775797 .7834911 

Ok 

RUN 

Random Number Seed (-32768 to 32767)? 3 
222 6007 .594141419 .2414202 .2013798 5.361748E-02 
Ok 


READ Statement 


Reads values from one or more DATA statement and assigns them 
to the specified variables. The READ statement is usually used in a 
program. 


READ variable[ , variable] ... 













Where 


SYNTAX ELEMENT 

MEANING 


variable 

Each variable in the list may be a numeric or string 
variable. The type of the variable must agree with 
the type of the associated value in the DATA state¬ 
ment sequence. 


Characteristics 

If the data type (numeric or string) of an entry in the data sequence 
does not correspond to the type of the associated variable, a ’’Syntax 
error” will result. However any numeric datatype (integer, single or 
double precision) may be assigned to any numeric variable. 

A single READ statement may access one or more DATA statements 
(they will be accessed in order), or several READ statements may ac¬ 
cess the same DATA statement. If the number of variables in the list 
of variables exceeds the number of elements in the DATA statement(s), 
an “Out of data” error message is printed. If the number of variables 
specified is fewer than the number of elements in the DATA state¬ 
ments), subsequent READ statements will begin reading data at the 
first unread element. If there are no subsequent READ statements, 
the extra data is ignored. 

To reread DATA statements from the start, use the RESTORE state¬ 
ment (see “RESTORE” later in this chapter). 
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Example 1 


80 FOR 1 = 1 TO 10 
90 READ A(l) 

100 NEXT I 

110 DATA 3.08,5.19,3.12,3.98,4.24 
120 DATA 5.08,5.55,4.00,3.16,3.37 


This program segment READs the values fron the DATA statements 
into the array A. After execution, the value of A(1) will be 3.08 the value 
of A(2) will be 5.19 and so on. 


Example 2 

10 PRINT “CITY”, “STATE”, “ZIP” 

20 READ C$,S$,Z 

30 DATA “DENVER,”, COLORADO, 80211 
40 PRINT C$,S$,Z 
Ok 

RUN 

CITY STATE ZIP 

DENVER COLORADO 80211 


This program READs string and numeric data from the DATA state¬ 
ment in line 30. 





REM Statement 


Allows explanatory remarks to be inserted in a program. 


REM remark 


Where 


SYNTAX ELEMENT 


MEANING 



remark 


Represents a sequence of characters 


Characteristics 

REM statements are not executed but are output exactly as entered 
when the program is listed. 

REM statements may be branched into from a GOTO or GOSUB state¬ 
ment. Execution will continue with the first executable statement after 
the REM statement. 

Remarks may be added to the end of a line by preceding the remark 
with a single quotation mark (’) instead of REM. The single quotation 
mark may also be entered just after the line number, like REM. 
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Do not use remarks in a DATA statement, because it would be con¬ 
sidered legal data. 


Examples 


120 

130 

140 

150 


or 


120 FOR 1 = 1 TO 20 ‘Calculate Average Velocity 
130 SUM = SUM + V(I) 

140 NEXT I 


or 


120 ‘Calculate Average Velocity 
130 FOR 1 = 1 TO 20 
140 SUM = SUM + V(l) 

150 NEXT I 


REM Calculate Average Velocity 
FOR I = 1 TO 20 
SUM = SUM + V(l) 

NEXT I 





RENUM Command 


Changes the line numbers of the current program. RENUM is usually 
used in immediate mode. 


RENUM [new-linenum][ , [old-linenum][ , increment ]] 


Where 


SYNTAX ELEMENT 

MEANING 


new-linenum 

Is the first line number to be used in the new se¬ 
quence. The default is 10. 

old-linenum 

Is the line in the current program where renumber¬ 
ing is to begin. The default is the first line of the 
program. 

increment 

Is the increment to be used in the new sequence. 
The default is 10. 
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Characteristics 

RENUM also changes all line number references following GOTO, 
GOSUB, THEN, ON...GOTO, ON...GOSUB, RESTORE, RESUME, 
and ERL statements to reflect the new line numbers. If a nonexistent 
line number appears after one of these statements, the error message 
’’Undefined line number xxxxx in yyyyy” is printed. The incorrect line 
number reference xxxxx is not changed by RENUM, but line number 
yyyyy may be changed. 

RENUM cannot be used to change the order of program lines or to 
create line numbers greater than 65529. An ’’Illegal function call” er¬ 
ror will result. 


Examples 

RENUM 

Renumbers the entire program. The first new line number will be 10. 
Lines will be numbered in increments of 10. 

RENUM 300,,50 

Renumbers the entire program. The first new line number will be 300. 
Lines will be numbered in increments of 50. 

RENUM 1000,900,20 

Renumbers the lines from 900 up, so they start with line number 1000 
and are numbered in increments of 20. 


RESET Command 


Closes all open data files on all drives. RESET is usually used in a 
program. 


RESET 









Characteristics 

RESET closes all open data files on all drives, and forces all blocks 
in memory to be written to disk. Thus,if the machine loses power, all 
files will be properly updated. All files must be closed before a disk 
is removed from its drive. 

Note that RESET performs the same action as CLOSE with no 
arguments, if all open data files are resident on disk. 


RESTORE Statement 


Permits DATA statements to be re-read either from the beginning of 
the internal data file or from a specified line. RESTORE is usually us¬ 
ed in a program. 


RESTORE [linenum] 


Where 


SYNTAX ELEMENT 

MEANING 


linenum 

Must be the line number of a DATA statement 


Characteristics 

After a RESTORE statement is executed, the next READ statement 
accesses the first item in the first DATA statement in the program. If 
linenum is specified, the next READ statement accesses the first data 
item in the specified DATA statement. 
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Example 

10 READ A,B,C 
20 RESTORE 
30 READ D,E,F 
40 DATA 58, 67, 97 


RESUME Statement 


Continues program execution after an error trapping routine has been 
performed. RESUME is usually used in a program. 


RESUME [ 0 I NEXT | linenum] 


Where 


SYNTAX 

MEANING 

RESUME or 

Execution resumes at the statement which caus¬ 

RESUME 0 

ed the error. 

RESUME NEXT 

Execution resumes at the statement immediately 
following the one which caused the error. 

RESUME linenum 

Execution resumes at the specified line. 















Remarks 

Any one of the four formats shown above may be used, depending 
upon where execution is to resume. 

A RESUME statement that is not in an error handling routine causes 
a ’’RESUME without error” message to be printed. 


Example 

10 ON ERROR GOTO 900 


900 IF (ERR = 230)AND(ERL = 90) THEN PRINT ’’TRY 
AGAIN”:RESUME 80 


RIGHT$ Function 


Returns a substring from a specified string, extracting its rightmost 
characters. 


RIGHT$ ( string , length ) 
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Where 

SYNTAX ELEMENT 

MEANING 

string 

Is a string expression whose value is the original 
string from which a substring is to be returned. 

length 

Is a numeric expression rounded to the nearest in¬ 
teger, whose value (from 0 to 255) represents the 
length of the returned string. 



Remarks 


If length is greater or equal to LEN(string), then the entire original 
string is returned. When length = 0, the null string (length of zero) is 
returned. 


Example 

10 A$ = ’’DISK GWBASIC” 
20 PRINT RIGHT$(A$,7) 

RUN 

GWBASIC 

Ok 
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Removes an existing directory. RMDIR is usually used in immediate 
mode. 


RMDIR pathname 


Where 


SYNTAX ELEMENT 

MEANING 


pathname 

Is the name of the directory which is to be deleted 


Characteristics 

RMDIR works exactly like the MS-DOS command RMDIR. The direc¬ 
tory to be deleted must be empty of all files and sub-directories ex¬ 
cept the working directory (’.’) and the parent directory entries, 
or a "Path not found” error is given. 
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Example 

ROOT 

/ \ 

SALES ACCOUNTS 

/ / \ 

FRED AMOS ANDY 

/ 

WILMA 


With reference to our sample structure above, we decide that we no 
longer want the sub-directory ANDY. Let us assume that our current 
directory is ROOT. Then: 

RMDIR ”ACCOUNTS\ANDY” 

deletes the directory ANDY. 

On the other hand, if you want to make ACCOUNTS the current direc¬ 
tory and remove the directory called AMOS then: 

CHDIR ’’ACCOUNTS” 

RMDIR ’’AMOS” 


Possible Errors 

’’Path not found” 

’’Bad File name” 

’’Path/File Access Error”: usually indicating that the directory is not 
empty. 





RND Function 


Returns a random number between 0 and 1. 


RND [ ( numexp ) ] 


Where 


SYNTAX ELEMENT 


numexp 


MEANING 


Is a numeric expression which modifies the return¬ 
ed value. 


Characteristics 

RND returns a uniformly distributed random number in the open inter¬ 
val between 0 and 1. Unless you write a RANDOMIZE statement before 
the RND statement, the same sequence of random numbers is 
generated on every run. 

RND acts differently depending upon whether the numeric expression 
evaluates to a positive number, negative number, or zero: 

• RND (positive number) returns the next number in the current se¬ 
quence 


RND (negative number) reseeds the random number generator and 
returns the first random number in the new sequence 


• RND(O) returns the last random number generated, without affec¬ 
ting the current sequence. 
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The numeric expression is optional. If you do not give one, RND acts 
as if you had given a positive expression as an argument. 

To return integer random numbers in the range 0 (zero) to N, use: 

INT (RND*(N +1)) 


Example 

10 FOR 1 = 1 TO 5 
20 PRINT INT(RND*100); 
30 NEXT 

RUN 

12 65 86 72 79 
Ok 


RUN Command 


Runs the current program or loads a program from disk into memory 
and runs it. 

Syntax 1 


RUN [linenum] 


Syntax 2 


RUN [filespec \ pathname^ ,R ] 














Where 


SYNTAX ELEMENT 

MEANING 


linenum 

Is the line number of the program resident in 
memory. If linenum is specified execution begins 
on that line. 

filespec (or 
pathname) 

Is a string expression which specifies the program 
to be loaded and run. 

R 

Specifies that all data files (that were opened before 
loading the designated program) remain open. 


Characteristics 

For a program currently in memory, if linenum is specified, execu¬ 
tion begins on that line, otherwise, execution begins at the lowest line 
number. To run a program which is not resident in memory, the 
filespec or pathname option must be entered. This option will 
specify the same filename that was used when the file was SAVEd. 
(MS-DOS will append a default .BAS filename extension if one was 
not supplied in the SAVE command.) 

RUN closes all open files and deletes the current contents of memory 
before loading the designated program. However, with the R option, 
all data files remain open. 
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Examples 

RUN ”B:NEWFILE”,R 
RUN A 
RUN 150 

RUN ”C:\R001\R002” 


SAVE Command 


Saves the program resident in memory onto disk and gives it a name. 
Option A saves the program in ASCII format. Option P saves it pro¬ 
tected. 


SAVE [filespec \ pathname] [ , [A |P ]] 


Where 


SYNTAX ELEMENT 

MEANING 

filespec (or 
pathname) 

Is a string expression which specifies the name of 
the file to be saved, and optionally the drive. If the 
filename extension is omitted, .BAS is assumed. 
If the drive is omitted, the default MS-DOS drive 
is assumed. 

A 

Saves the program file in ASCII format. If the A op¬ 
tion is not specified, GW-BASIC saves the file in 
a compressed binary format. 














SYNTAX ELEMENT 

MEANING 


P 

Protects the file by saving it in an encoded binary 
format. When a protected file is later run (or LOAD- 
ed), any attempt to list or edit it will fail. 


Characteristics 

If a file with the same name already exists on the selected disk, it will 
be written over. 

GW-BASIC saves the file in a compressed binary format, unless the 
A option is specified. 

ASCII format takes more space on disk, but some disk access requires 
that files be in ASCII format. For instance, the MERGE command re¬ 
quires an ASCII format file, and some MS-DOS commands such as 
TYPE may require an ASCII format file. 

Attempts to MERGE binary programs will result in a ’’Bad file mode” 
error. 


Examples 

SAVE ’’SUPERB” 

Saves the program in memory on the default drive as SUPERB.BAS. 

SAVE ”A:PROG”,A 

Saves in ASCII the program in memory on the diskette inserted on 
drive A, as PROG.BAS. 

SAVE ”B:SECRET”,P 

Saves the program in memory in protected form, on the diskette in¬ 
serted on drive B, as SECRET.BAS. 
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SCREEN Function 


Returns either the ASCII code (0-255) or the color number for the 
character at the specified screen location. 


SCREEN( row , column] , condition ]) 


Where 


SYNTAX ELEMENT 

MEANING 

row 

Is a numeric expression returning an unsigned in¬ 
teger in the range 1 to 25 

column 

Is a numeric expression returning an unsigned in¬ 
teger the range of which depends on the screen 
width 

condition 

Is a valid numeric, relational or logical expression 
returning a boolean result (0 or 1). If condition is 
given as non-zero, the color number for the 
character is returned instead of the ASCII code. 

Characteristics 


The SCREEN function returns zero if the system is in one of the 
graphics modes and the specified screen location contains graphics 
data. 


Refer to Appendix C for a complete list of ASCII codes. 














Examples 

100 X = SCREEN (10,10) ’If the character at 10,10 is A then 65 

is returned. 


110 X = SCREEN (1,1,1) ’Returns the color number of the 

character in the upper left hand cor¬ 
ner of the screen. 


Errors 

If you enter a value outside the above mentioned ranges, an ’’Illegal 
function call” error is returned. 


SCREEN Statement 


Allows you to pass from Text Mode to one of the graphics modes. It 
also allows you to enable/disable color and to select the active and 
visual page (in Text Mode). 


SCREEN [mode] [ , [burst] [ , [apage] [ , vpage]]] 
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Where 


SYNTAX ELEMENT 

MEANING 

mode 

Is a numeric expression resulting in an integer 
value in the range 0 to 255. It defines either Text 
Mode (0), Medium-Resolution Graphics Mode (1), 
High-Resolution Graphics Mode (2), or Super- 
Resolution Graphics Mode (3 to 255). 

burst 

Is a numeric expression resulting in an integer 
value of 0 or 1. It enables color on a non-standard 
monitor. In Text Mode a 0 value disables color, and 
a 1 value enables color. In Medium Resolution a 
0 value enables color, and a 1 value disables col¬ 
or. Both in High Resolution and Super Resolution 
the burst value is ignored, as these two modes on¬ 
ly support monochrome. 

For a standard monitor, this parameter has no 
meaning. 

apage (Text Mode 
only) 

Is an integer expression in the range 0 to 7 for width 
40, or 0 to 3 for width 80. It selects the active page, 
i.e. the page to be written to by output statements 
to the screen. If omitted, the active page defaults 
to 0. 

i /page (Text Mode 
only) 

Is an integer expression in the range 0 to 7 for width 
40, or 0 to 3 for width 80. It selects the visual page, 
i.e. the page to be displayed on the screen which 
may be different from the active page. If you omit 
this parameter the visual page will default to the 
active page. 










mode and burst Parameters 


In the following table the first two columns are the mode and 
burst parameters of a SCREEN statement. 

The burst parameter enables color on non-standard color monitors. 
For systems with standard monitors, this parameter has no real mean¬ 
ing. For example a burst value of 0 or 1 in Medium Resolution will have 
the same effect if a standard color monitor is used; likewise it will have 
the same effect if a standard monochrome monitor is used (in this case 
the four colors will appear as shades of grey). 


mode 

burst 

Description 

0 

0 

80 c. x 25 r. - BA N Text Mode 

0 

1 

80 c. x 25 r. - Color Text Mode 

1 

0 

320 hor.pixels x 200 vert. 
pixels-Color Medium Resolu¬ 
tion Graphics Mode (40 c. x 
25 r.) 

1 

1 

320 hor.pixels x 200 vert. 
pixels-BA N Medium Resolu¬ 
tion Graphics Mode (40 c. x 
25 r.) 

2 

x (ignored) 

640 hor.pixels x 200 vert. 
pixels-BA N High Resolution 
Graphics Mode (80 c. x 25 r.) 

3-255 

x (ignored) 

640 hor.pixels x 400 vert.pix- 
els BA/V Super Resolution 
Graphics Mode (80 c. x 25 r.) 


Tab. 8-3 Use of mode and burst Parameters 
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Default Values 

If you do not enter a SCREEN statement, the system assumes the 
following default values: 

mode = 0 (Text Mode) 
burst = 0 (B/W) 
apage = 0 (active page 0) 
vpage = 0 (virtual page 0) 

The SCREEN statement must precede any I/O statement to the screen, 
that uses attributes different to those currently in force. You can use 
more than one SCREEN statement to define different screen attributes 
for different sections of your program. 


Active and Visual Pages 

If Text Mode is selected, you can specify two more parameters 
(apage and vpage) to select the active and visual page. There are 
eight display pages (numbered 0 to 7) in 40-column Text Mode, and 
four display pages (numbered 0 to 3) in 80-column Text Mode. Only 
one display page is available in any of the three graphics modes. 

Only one cursor is shared between the pages, thus, if you select a 
new active page, you must save the cursor position (by POS(O) and 
CSRLIN) before changing to the new page. If you return to the original 
active page, you must restore the cursor position by the LOCATE (Text) 
statement. If you use the SCREEN statement only to change the pages, 
you can omit the first two parameters (mode and burst). 


Screen Width 

At initialization the screen width is 80 columns, thus you should use 
the WIDTH statement to select a 40-column screen. If you select the 
Medium Resolution by the SCREEN statement, this also causes the 
number of columns to be 40 (without using the WIDTH statement). 




In Text Mode, the WIDTH statement may be used to select between 
the 40-column mode and the 80-column mode. Likewise, the WIDTH 
statement may be used to select between modes 1 and 2 (Medium 
or High resolution mode). 

Selecting Text Mode (mode = 0) after selection of one of the graphics 
modes will select either a 40-column screen or an 80-column screen, 
depending on the width used in the graphics mode. For example: 

SCREEN 1 Set Screen to Medium Res. Mode (WIDTH = 40) 
SCREEN 0 Changes Screen to 40x25 Text Mode (WIDTH = 40) 


Remarks 


IF... 

THEN... 

all parameters are 
valid 

the new screen mode is saved, the screen is eras¬ 
ed, the foreground and the background colors are 
set to their default values. 

ail parameters are 
identical to the 
preceding ones 

nothing is altered. 

you omit a parameter 

it assumes the preceding value (except for the 
visual page that defaults to the active page). 


GW-BASIC INTERPRETER USER GUIDE 


8-304 











COMMANDS, STATEMENTS AND FUNCTIONS 


Examples 

10 SCREEN 0,1,0,0 
Select Text mode with color, 

Active and visual page to 0. 

20 SCREEN ,,1,2 
mode and burst unchanged, 
use active page 1, 
display page 2. 

30 SCREEN 2 

Switch to High Res. Graphics Mode. 

40 SCREEN 1,1 

Switch to Medium Res. Color Graphics. 
50 SCREEN ,0 

Medium Res. Graphics, color off. 


Possible Errors 

If you enter a value outside the specified ranges, an ’’Illegal function 
call” error is returned. If no parameters are given, a “Missing Operand” 
error message will be generated. 


SGN Function 


Returns a value determined by the sign of the specified numeric 
expression. 


SGN( numexp ) 


Characteristics 


If 

If 

If 


numexp >0, SGN( numexp ) returns 1. 
numexp =0, SGN( numexp ) returns 0. 
numexp <0, SGN( numexp ) returns -1. 










Example 

50 ON SGN(X) + 2 GOTO 300,400,500 

branches to 300 if numexp is negative, 400 if numexp is 0, and 
500 if numexp is positive. 


=== SHELL Command 


Loads into memory and executes another program (.EXE or .COM or 
.BAT). 


SHELL [stringexp] 


Where 


SYNTAX ELEMENT 

MEANING 


stringexp 

Is a string expression containing the name of a pro¬ 
gram to run and (optionally) command arguments 


Characteristics 

When the program finishes, control returns to the GW-BASIC program 
at the statement following the SHELL command. A program executed 
under control of GW-BASIC is referred to as a ’’Child process”. 
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Child processes (or ’’children”) are executed by SHELL loading and 
running a copy of COMMAND with the 1C switch. By using COMMAND 
this way command line parameters are passed to the child. Standard 
Input and Output may be selected, and Built-in Commands such as 
DIR, PATH, and SORT may be executed. 


Remarks 

The program name in stringexp may have any extension you want 
since COMMAND has to worry about it. If no extension is supplied, 
COMMAND will look for a .COM file, then a .EXE file, and finally, a 
.BAT file. If COMMAND is not found, SHELL will issue a ’’File not 
found” error. No GW-BASIC error is generated if COMMAND cannot 
find the file specified in stringexp . 

Any text in stringexp separated from the program name by at least 
1 blank, will be processed by COMMAND as a sequence of program 
parameters. 

GW-BASIC remains in memory while the child process is running. 
When the child finishes, GW-BASIC continues. 

SHELL with no stringexp will give you a new COMMAND shell. You 
may now do anything that COMMAND allows. When ready to return 
to GW-BASIC, enter the MS-DOS command: EXIT. 


Examples 

SHELL (get a new COMMAND) 

A> DIR (user enters DIR to see files) 

A> EXIT (user enters EXIT to return to GW-BASIC) 


The following example writes some data to be sorted, uses SHELL 
to execute SORT to sort it, then reads the sorted data to write a report. 

900 OPEN ’’SORTIN.DAT” FOR OUTPUT AS #1 

950 REM write data to be sorted 

1000 CLOSE 1 





1010 SHELL ’’SORT <SORTIN.DAT >SORTOUT.DAT” 
1020 OPEN ’’SORTOUT.DAT” FOR INPUT AS #1 
1030 REM Process the sorted data 

10 SHELL ”DIR | SORT > FILES. 

20 OPEN ’’FILES.” FOR INPUT AS #1 


Possible Errors 

’’File not found”: if COMMAND could not be found. 

’’Out of memory”: there was not enough memory to run the Child. 

’’Can’t continue after SHELL”: there is not enough memory for GW- 
BASIC to continue. All files are closed and GW-BASIC returns to MS- 
DOS. This may happen when a Child process ’’terminates and stays 
resident”. 

’’Internal error”: either GW-BASIC or MS-DOS is not functioning 
correctly. 

“You cannot SHELL to BASIC”: it is not permitted to invoke GW-BASIC 
after a SHELL. 


SIN Function 


Calculates the sine of the argument. 


SIN( numexp ) 


Characteristics 

The SIN function is calculated in single precision, unless ID is sup¬ 
plied in the GWBASIC command line. 
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Example 

PRINT SIN(1.5) 

.9974951 

Ok 

SOUND Statement 

Produces sound. 


SOUND frequency , duration 


Where 


SYNTAX ELEMENT 

MEANING 

frequency 

Is a numeric expression from 37 to 32767. It 
represents the frequency in Hertz 

duration 

Is the duration in clock ticks. Clock ticks occur 18.2 
times per second. Duration is an integer expres¬ 
sion from 0 to 65535. 





















Characteristics 


If the duration is zero, any SOUND statement that is running will be 
turned off. If no SOUND statement is currently running, a SOUND state¬ 
ment with a duration of zero will have no effect. 


This following table displays the frequencies of musical notes (two oc¬ 
taves below and two octaves above middle C). 


1975.5 

1760.0 

1568.0 

1396.9 

1318.5 

1174.7 

1046.5 

B 

A 

G 

F 

E 

D 

C 

987.77 

880.00 

783.99 

698.46 

659.26 

587.33 

523.25 

B 

A 

G 

F 

E 

D 

C 

493.88 

440.00 

392.00 

349.23 

329.63 

293.66 

261.63 

B 

A 

G 

F 

E 

D 

C 

246.94 

220.00 

196.00 

174.61 

164.81 

146.83 

130.81 

B 

A 

G 

F 

E 

D 

C 
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Tempos and Beats/Minute 


TEMPOS 

BEATS/MINUTE 

TICKS/BEAT 

Larghissimo 



Largo 

40-60 

28.13-18.75 

Larghetto 

Grave 

Lento 

60-66 

18.75-17.05 

Adagio 

66-76 

17.05-14.8 

Adagietto 



Andante 

76-108 

14.8-10.42 

Andantino 



Moderato 

108-120 

10.42-9.38 

Allegretto 



Allegro 

Vivace 

Veloce 

120-168 

9.38-6.7 

Presto 

168-208 

6.7-5.41 

Prestissimo 

greater than 208 

less than 5.41 


Tab. 8-4 Tempos and Beats/Minute 


Example 

100 SOUND RND* 1000 + 37,2 
This statement creates random sounds. 












SPACES Function 


Returns a string of a specified number of spaces. 


SPACE$( length ) 


Where 


SYNTAX ELEMENT 

MEANING 


length 

Is an integer expression from 0 to 255. It specifies 
the number of spaces i.e. the length of the return¬ 
ed string. 


Example 

10 FOR 1 = 1 TO 5 
20 X$ = SPACE$(I) 
30 PRINT X$;l 
40 NEXT I 

RUN 

1 

2 

3 

4 

5 
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Possible Errors 


If length is outside the specified range, an ’’Illegal function call” 
error is returned. 


SPC Function 


Skips spaces in a PRINT, LPRINT, or PRINT# statement. 


SPC( n ) 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression from 0 to 255. It specifies 
the number of spaces to be inserted in the output 
line. 

Remarks 


SPC may only be used with PRINT, LPRINT and PRINT statements. 



If n is greater than the defined width, then the value used is n 
MOD width . A semicolon (;) is assumed to follow the SPC function; 
thus GW-BASIC does not add a carriage return, if you enter an SPC 
function at the end of a list of data. 
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If n is outside the specified range an ’’Illegal function call” error 
is returned. 


Example 

PRINT ’’FOUR” SPC(15) ’’SEASONS” 
FOUR SEASONS 

Ok 


-SQR Function 


Returns the square root of a positive numeric expression. 


SQR( numexp ) 


Remarks 

SQR is calculated in single precision, unless the ID switch is supplied 
in the GWBASIC command line. 

An ’’Illegal function call” error results if the argument is negative. 


Example 

10 FOR X = 10 TO 25 STEP 5 
20 PRINT X, SQR(X) 

30 NEXT 


RUN 


10 

3.162278 

15 

3.872984 

20 

4.472136 

25 

5 

Ok 
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STOP Statement 


Interrupts program execution then returns to command level. 
STOP is only used in a program. 


STOP 


Characteristics 

A STOP statement may be used anywhere in a program. When a STOP 
is encountered, the following message is displayed: 

Break in nnnnn 

The STOP statement does not close files, unlike the END statement. 

GW-BASIC always returns to command level after a STOP is executed. 
Execution is resumed by issuing a CONT command. 


Example 

10 INPUT A,B,C 

20 K = A a 2*5.3:L = B a 3/.26 

30 STOP 

40 M = C*K+ 100:PRINT M 

RUN 

? 1,2,3 

Break in 30 

Ok 













PRINT L 

30.76923 

Ok 

CONT 

115.9 

Ok 


STR$ Function 


Returns the string representation of the value of a specified numeric 
expression. 


STR$( numexp ) 


Example 

10 A$ = STR$(70) 

20 PRINT A$ 

Ok 

RUN 

70 

Ok 

70 (the argument of STR$) is a number, but the contents of A$ is a 
three character string whose value is 70. The first character holds the 
sign of the number; a blank for positive, a minus sign for negative. 
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Example 


5 REM ARITHMETIC FOR KIDS 

10 INPUT ’’TYPE A NUMBER”;N 

20 ON LEN(STR$(N)) GOSUB 30,100,200,300,400,500 


The entered number N is converted to a string by the STR$ function. 


Example 

10 A = 1.3 

20 A = VAL(STR$(A!)) 
30 PRINT A 
Ok 

RUN 



VAL is the complementary function of STR$. 


STRINGS Function 



Returns a string of specified length whose characters all have the same 
ASCII code or equal the first character of a given string. 

Syntax 1 
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STRING$( length , code ) 











Syntax 2 


STRING$( length , stringexp ) 

Where 


SYNTAX ELEMENT 

MEANING 

length 

Is an integer expression in the range 0 to 255. It 
specifies the length of the resulting string. 

code 

Is an integer expression in the range 0 to 255. It 
specifies the ASCII code whose corresponding 
character is used to form the resulting string. 

stringexp 

Is a string expression whose first character is us¬ 
ed to form the resulting string. 

Example 


10 X$ = STR1 NG$( 10,45) 

20 PRINT X$;”MONTHLY REPORT”;X$ 

RUN 

-MONTHLY REPORT- 

Ok 
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Example 

10 LET A$ =’’HOUSTON” 
20 LET X$ = STRING$(8,A$) 
30 PRINT X$ 

RUN 

HHHHHHHH 


SWAP Statement 


Exchanges the values of two variables. 


SWAP variable 1 , variable2 


Where 


SYNTAX ELEMENT 

MEANING 

variable 1 and 
variable2 

Are two variables of the same type (integer, single¬ 
precision, double-precision, or string) 


Remarks 

The two variables to be exchanged must be of the same type or a ’’Type 
mismatch” error occurs. If the second variable is not already defined 
when SWAP is executed, an ’’Illegal function call” error will result. 













Example 


Ok 

10 A$ = ” ONE ” : B$ = ” ALL ” : C$ = ”FOR” 

20 PRINT A$ C$ B$ 

30 SWAP A$, B$ 

40 PRINT A$ C$ B$ 

RUN 

ONE FOR ALL 
ALL FOR ONE 
Ok 

After line 30 is executed, A$ has the value ” ALL ” and B$ has the 
value ” ONE 






SYSTEM Command 


Closes all open data files and returns control to MS-DOS. 


SYSTEM 


Characteristics 

When a SYSTEM command is executed, all open files are closed, the 
current program is lost, and control is returned to MS-DOS. If GW- 
BASIC has been entered through a Batch file from MS-DOS, SYSTEM 
returns control to the Batch file. 
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TAB Function 


Tabs the cursor or the print head to a specified position in PRINT, 
LPRINT, or PRINT# statements. 


TAB( n ) 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer expression from 1 to 255 

Characteristics 



If the current cursor or print position is already beyond the specified 
value n , TAB goes to that position on the next line. Space 1 is 
the leftmost position, and the rightmost position is the width minus one. 

If the value of n exceeds the defined width, the modulo operation 
is applied. For example PRINT TAB(243) on a 40-column screen is 
the same as PRINT TAB(3), because 243 MOD 40 = 3. 

A semicolon is assumed to follow the TAB function, thus GW-BASIC 
does not add a carriage return if you enter a TAB function at the end 
of a list of data. 
















Example 


10 PRINT ’’NAME” TAB(25) ’’AMOUNT” : PRINT 
20 READ A$,B$ 

30 PRINT A$ TAB(25) B$ 

40 DATA ”G. T. JONES”,”$25.00” 

RUN 

NAME AMOUNT 


G. T. JONES $25.00 

Ok 


TAN Function 


Returns the tangent of the argument. 


TAN( numexp ) 


Where 


SYNTAX ELEMENT 

MEANING 


numexp 

Is a numeric expression representing the angle in 
radians 


• 
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Characteristics 

TAN(numexp) is calculated in single precision (unless ID is supplied 
in the GWBASIC command line). 

If TAN overflows, the ’’Overflow” error message is displayed, machine 
infinity with the appropriate sign is supplied as the result, and execu¬ 
tion continues. 


Example 

PRINT TAN (3.14/4) 
.999204 
Ok 


TIME$ Statement and Function 


The TIME$ statement sets the current time. 
The TIMES function retrieves the current time. 
Syntax 1: statement 


TIMES = stringexp 


Syntax 2: function 


stringvar = TIMES 













Where 


SYNTAX ELEMENT 


MEANING 


stringexp 


Is a string expression indicating the time to be set 


stringvar 


Is a string variable in which the current time (8 
character string) is returned 


Characteristics 

As a statement (to set the time): 

stringexp is a string expression indicating the time in one of the follow¬ 
ing forms: 

hh (sets the hour; minutes and seconds default to 00) 

hh:mm (sets the hour and minutes; seconds default to 00) 

hh:mm:ss (sets the hour, minutes and seconds) 

A 24 hour clock is used; therefore 8:00 p.m. would be entered as 
20 : 00 : 00 . 

You may omit a leading zero to specify the values of hours, minutes 
and seconds, but you must enter at least one digit. The time may also 
have been set by MS-DOS prior to entering GW-BASIC. 

As a function (to retrieve the time): 

The TIMES function returns an eight character string in the form 
hh:mm:ss, where hh is the hour (00 through 23), mm is minutes (00 
through 59), and ss is seconds (00 through 59). 
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Example 

TIME$ = ”8:0” 
Ok 

PRINT TIME$ 

08:00:04 

Ok 


Example 

The following program displays the current date and time on the 25th 
line of the screen and will ’’chime” on the hour. 

10 KEY OFF:SCREEN 0:WIDTH 40:CLS 
20 LOCATE 25 
30 PRINT DATE$,TIME$ 

40 SEC = VAL(MID$(TIME$,7,2)) 

50 IF SEC = SSEC THEN 20 ELSE SSEC = SEC 
60 IF SEC = 0 THEN 1010 
70 IF SEC = 30 THEN 1020 
80 IF SEC < 57 THEN 20 

1000 SOUND 1000,2:GOTO 20 
1010 SOUND 2000,8:GOTO 20 
1020 SOUND 400,4 :GOTO 20 


Possible Errors 

An ’’Illegal function call” error is returned, and the previous time is 
retained, if you enter a value outside the corresponding range. 

A ’’Type mismatch” error is returned, if you do not enter a valid string 
for stringexp 





TIMER Function 


Returns a single-precision number indicating the seconds that have 
elapsed since midnight or system reset. 


TIMER 


Characteristics 


TIMER is a numeric function. It calculates fractional seconds to the 
nearest degree possible. It may not be used as a user variable. 


Example 


10 FOR K = 1 TO 10 
20 PRINT ’’TIMER = ”;TIMER 
30 NEXT 


==== TIMER Statements 


TIMER ON enables TIMER event trapping. 
TIMER OFF disables TIMER event trapping. 
TIMER STOP suspends TIMER event trapping. 


TIMER [ON | OFF | STOP) 
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Remarks 

The TIMER ON statement enables real time event trapping by an ON 
TIMER(n) GOSUB statement. While trapping is enabled, GW-BASIC 
checks between every statement to see if the timer has reached the 
specified level. If it has, the ON TIMER(n) GOSUB statement is ex¬ 
ecuted. 

TIMER OFF disables the event trap. If an event takes place, it is not 
remembered if a subsequent TIMER ON is used. 

TIMER STOP disables the event trap, but if an event occurs, it is 
remembered and an ON TIMER(n) GOSUB statement will be executed 
as soon as trapping is enabled. 

When an ON TIMER(n) GOSUB is performed, an automatic TIMER 
STOP is executed. Once an error trap takes place, all trapping is 
automatically disabled. 

Also see ON TIMER(n) GOSUB statement in this chapter. 


TRON/TROFF Commands === 


TRON (TRACE ON) causes the line number of each statement ex¬ 
ecuted to be listed. 

TROFF (TRACE OFF) stops the line number listing initiated by TRON. 
Syntax 1 


TRON 











TROFF 


Characteristics 

The TRON command (executed in either immediate or program mode) 
is used as a debugging tool. With TRON in operation, each line number 
of the program is displayed on the screen as it is executed. The 
numbers appear enclosed in square brackets. The trace flag is disabled 
with the TROFF command (or when a NEW command is executed). 


Example 


TRON 

Ok 

LIST 

10 K = 10 

20 FOR J = 1 TO 2 
30 L = K + 10 
40 PRINT J;K;L 
50 K = K + 10 
60 NEXT 
70 END 
Ok 
RUN 

[40] 1 10 20 
[40] 2 20 30 

[60][70] 

Ok 

TROFF 

Ok 


[10] 

[20] 

[30] 

50 

60 

30 

50 

60 

70 
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UNLOCK Statement 


The UNLOCK statement releases locks applied to a opened file. This 
statement is only of use if MS-NET is installed with MS-DOS release 
3.1 or later. 


UNLOCK [#] filenum [, [recordnuml] [TO recordnum2 ]] 

Where 

SYNTAX ELEMENT 

MEANING 

filenum 

Is the file number of the opened file. 

recordnum 1 

Is the number of the record at which unlocking 
begins. If this parameter is omitted record number 
1 is assumed. 

recordnum2 

Is the number of the record at which unlocking ter¬ 
minates. If this parameter is omitted, only one 
record recordnuml is unlocked. 



Characteristics 


If a record number or range of record numbers is specified, and the 
file is opened in random mode, only those records in the range are 
unlocked. The record number range must exactly match the record 
number range given in the LOCK statement or a “Permission denied” 
error message will be returned. 


See also the LOCK and OPEN statements. 





















If you try and use this statement with an MS-DOS release prior to 3.1 
yu will get an “Advanced Feature Error”. If you are using MS-DOS 
3.1 or later, but MS-NET is not installed, you will get a “Permission 
Denied” error. The MS-DOS command SHARE must also be given 
(either at the MS-DOS prompt or from an AUTOEXEC.BAT file). See 
the “MS-DOS User Guide” for a full description of procedures to be 
followed for networking. 

The suggested usage of files on shared devices is for a LOCK to be 
executed on a file, or record range within a file, before an attempt is 
made to read or write to that file. It is also recommended that the file 
or range be UNLOCKed before the file is closed (failure to do so may 
cause problems for future access to that file in a network environment). 
The time in which files are locked should be kept to minimum. 


Examples 

LOCK #1, 1 TO 4 
LOCK #1, 5 TO 8 


UNLOCK #1, 1 TO 4 
UNLOCK #1, 5 TO 8 

Note that the UNLOCK statements in the above example cannot be 
replaced by the single statement: 

UNLOCK #1, 1 TO 8 


Possible Errors 

“Permission Denied”: MS-NET not installed or no preceding matching 
LOCK statement. 
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USR Function 


Calls a machine language subroutine. USR is usually used in a 
program. 


USR [n] ( argument ) 


Where 


SYNTAX ELEMENT 

MEANING 

n 

Is an integer from 0 to 9. It specifies which USR 
subroutine is being called. If omitted USRO is 
assumed. 

argument 

Is the value passed to the subroutine. It may be any 
numeric or string expression. Even if the subroutine 
does not require an argument, a dummy argument 
must be supplied. 

Characteristics 


The type (numeric or string) of the variable receiving the function call 
must be consistent with that of the argument passed. 

Prior to calling each USR function, a corresponding DEF USR state¬ 
ment must be executed to define the offset of the subroutine with 
respect to the start address of the segment, specified in the last DEF 
SEG statement executed. 













If no DEF SEG has been executed the start address of the default seg¬ 
ment (the GW-BASIC Data Segment) will be used. 

The CALL statement is another way to call a machine language 
subroutine. 


Example 

100 DEF SEG = &H8000 
110 DEF USR0 = 0 
120 X = 5 

130 Y = USR0(X) 

140 PRINT Y 


VAL Function 


Converts the string representation of a number to its numeric value. 


VAL( stringexp) 


Characteristics 

The VAL function strips leading blanks, tabs, and linefeeds from the 
argument string. 

The remaining string is converted to a number, if it is a valid numeric 
representation, otherwise VAL returns 0 (zero). For example: 

VAL(” -3”) 

returns -3. 

VALf’ABC”) 

returns 0 
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Example 

10 READ NAMES,CITYS,STATES,ZIPS 
20 IF VAL(ZIP$) <90000 OR VAL(ZIP$)> 96699 
THEN PRINT NAMES TAB(25) ’’OUT OF STATE” 
30 IF VAL(ZIP$)> =90801 AND VAL(ZIP$)< =90815 
THEN PRINT NAMES TAB(25) ’’LONG BEACH” 


VARPTR Function 


VARPTR ( variable ) returns the memory address of variable. 
VARPTR (* filenum) returns the starting address of the File Control 
Block (FOB) associated with the file specified in filenum. 

Syntax 1 


VARPTR (variable) 


Syntax 2 


VARPTR (# filenum) 














Where 


SYNTAX ELEMENT 

MEANING 


variable 

Is any numeric or string program variable 


filenum 

Is the number assigned to the file when it 
opened 

was 


Remarks 

For both syntax 1 and 2, the address returned will be an integer in 
the range 0 to 65535. This integer value is the offset into GW-BASIC’s 
Data Segment. 


Syntax 1 

Returns the address of the first byte of data identified with variable . 

The variable must have been defined prior to execution of 
VARPTR. Otherwise an ’’Illegal function call” error results. Variables 
are defined by executing any reference to the variable. Both numeric 
and string variables may be used. For string variables, the address 
of the first byte of the string description is returned (see Appendix F). 

VARPTR is usually used to obtain the address of a variable or array 
so that it may be passed to an machine language subroutine. A func¬ 
tion call of the form VARPTR(A(0)) is usually specified when passing 
an array, so that the lowest-addressed element of the array is returned. 
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All simple variables should be assigned before calling VARPTR for an 
array, because the addresses of the arrays change whenever a new 
simple variable is assigned. 


Syntax 2 

For sequential files, VARPTR (# filenum ) returns the starting address 
of the File Control Block (FCB) 

Example 

10 X = USR(VARPTR(Y)) 


Example 

100 FIELDADDRESS = VARPTR( #2) 


VARPTR$ Function === 


Returns the memory address of the variable in string format. 


VARPTR$ ( variable) 


Characteristics 

VARPTR$ is primarily used to execute substrings with the DRAW and 
PLAY statements in programs that will later be compiled. With pro¬ 
grams that will not be later compiled, the standard syntax of the DRAW 
and PLAY statements will be sufficient to produce the desired effects. 









For example: 

PLAY ”XA$;” 
and 

PLAY ”X” + VARPTR$(A$) 

produce the same effect. 

The variable must have been defined prior to the execution of the 
VARPTR$ function, otherwise, an ’’Illegal function call” error results. 
Variables are defined by executing any reference to the variable. Both 
numeric and string variables may be used. 

VARPTR$ returns a three-byte string in the form: 

byte 0 = type of the variable 
byte 1 = low byte of address 
byte 2 = high byte of address 

Note that type specifies the type of the variable, as follows: 

2 integer 

3 string 

4 single-precision 
8 double-precision 

Because array addresses, string addresses and file data block change 
whenever a new variable is defined, it is unsafe to save the result of 
a VARPTR$ function in a variable. It is recommended that VARPTR$ 
is executed before each use of the result. 


VIEW Statement 


Defines the dimensions and position of the viewport for graphics ac¬ 
tivity. (Graphics Mode only.) 


VIEW [[ SCREEN ][ ( vxl, vyl )-( vx2, vy2 ) [, [ color ] [, [ border ]]]] 
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Where 


SYNTAX ELEMENT 

MEANING 

(vxl ,vy1)(vx2,vy2) 

(vx1,vy1) are the upper-left, and (vx2, vy2) the 
lower-right coordinates of the viewport defined. 

color 

Permits the viewport to be filled with a specified col¬ 
or. If color is omitted then the viewport is not 
filled-in. 

border 

Permits the drawing of a border-line surrounding 
the viewport (if the necessary space for a border 
is available). If border is omitted, no border-line is 
drawn. A value of 1 indicates a border, and 0 in¬ 
dicates no border. 


Characteristics 

VIEW defines a rectangular area on the screen, the viewport, in which 
graphics are displayed, by specifying the top-left coordinates ( vx1,vy1) 
and the bottom-right coordinates (vx2,vy2). 

A VIEW statement without parameters defines the whole screen as 
the viewport. 


SCREEN Option 

The SCREEN option specifies that the x and y coordinates of all points 
are to be taken absolute to the screen (the origin is the top-lefthand 
corner of the screen); but only the points within the viewport will be 
displayed. 










Using the format: 

VIEW (vxl,vy1)-(vx2,vy2) 

the coordinates, x and y, of all points will be taken as relative to the 
viewport. Therefore, given the following statements: 

VIEW (10,10)-(200,100) 

PSET (0,0) ,3 

the point specified in the PSET statement will actually be positioned 
at (10,10) on the screen. Likewise, if a WINDOW statement is executed, 
all the points inside the window will be projected onto the correspon¬ 
ding points inside the viewport defined by VIEW. 

Using the format: 

VIEW SCREEN (vxl t vy1)-(vx2,vy2) 

the coordinates, x and y, of all points will be taken as absolute. 
Therefore, given the following statements: 

VIEW SCREEN (10,10)-(200,100) 

PSET (0,0) ,3 

the point specified in the PSET statement will not be displayed, 
because the point (0,0) falls outside of the area of the viewport; the 
statement PSET (10,10) ,3 would result in the point at the top-lefthand 
corner of the viewport being displayed. If a WINDOW statement is ex¬ 
ecuted, all the points inside the window will be projected onto the cor¬ 
responding points on the screen, but only those points within the 
viewport, defined by VIEW SCREEN, would be displayed. 


Multiple Viewports 

Any number of VIEW statements can be executed. Each execution 
of the VIEW statement results in the definition of a viewport that is then 
the current viewport. In order to change the current viewport, you must 
execute another VIEW statement. 
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Viewports can be completely or partially overlapped. In order to erase 
all previously defined viewports, you must use a VIEW statement 
without parameters (defining the whole screen as the viewport) and 
then execute a CLS statement to clear the contents of the current 
viewport. 


Examples 

See the examples given with the WINDOW statement. 


WAIT Statement - 


Suspends program execution while monitoring the status of a machine 
input port. WAIT may only be used in a program. 


WAIT port , /[ , j] 


Where 


SYNTAX ELEMENT 

MEANING 

port 

Represents a port number, i.e., an integer from 0 
to 65535 

U 

Are integer expressions from 0 to 255 













Characteristics 

The WAIT statement causes execution to be suspended until a 
specified machine input port develops a specified bit pattern. The data 
read at the port is XORed with the integer expression j, and then AND- 
ed with /. If the result is zero, GW-BASIC loops back and reads the 
data at the port again. If the result is nonzero, execution continues 
with the next statement. If j is omitted, it is assumed to be zero. 


It is possible to enter an infinite loop with the WAIT statement. 


Example 

100 WAIT 32,2 


WHILE...WEND Statements 


Execute a series of statements in a loop as long as a given condition 
remains true. 


WHILE condition 


[loop statements] 

WEND 
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Where 

SYNTAX ELEMENT 

MEANING 

condition 

Is a numeric, relational or logical expression. GW- 
BASIC determines whether the condition is true or 
false by testing the result of the expression for non 
zero and zero, respectively. A non zero result is true 
and a zero result is false. Because of this, you can 
test whether the value of a variable is non zero or 
zero by merely specifying the name of the variable 
as a condition. 

loop statements 

Are executed until a WEND statement is 
encountered 


Characteristics 

If condition is not zero (i.e., true), loop statements are executed 
until the WEND statement is encountered. GW-BASIC then returns to 
the WHILE statement and checks condition . If it is still not zero, 
the process is repeated. If it is zero (i.e. false), execution resumes with 
the statement following the WEND statement. 


WHILE/WEND loops may be nested to any level. Each WEND will 
match the most recent WHILE. An unmatched WHILE statement 
causes a ’’WHILE without WEND” error, and an unmatched WEND 
statement causes a ’’WEND without WHILE” error. 

Do not direct program flow into a WHILE/WEND loop without entering 
through the WHILE statement. 









Example 

90 ’BUBBLE SORT ARRAY A$ 

100 FLIPS = 1 ’FORCE ONE PASS THRU LOOP 

110 WHILE FLIPS 

115 FLIPS = 0 

120 FOR I = 1 TO J-1 

130 IF A$(I)>A$(I + 1) THEN 

SWAP A$(I),A$(I +1 ):FLIPS = 1 

140 NEXT I 

150 WEND 


- WIDTH Statement 


Sets the line width in characters. GW-BASIC adds a carriage return 
after outputting the specified number of characters. 

Syntax 1 


WIDTH [LPRINT]s/ze 


Syntax 2 


WIDTH # filenum , size 
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Syntax 3 


WIDTH device , size 

Where 

SYNTAX ELEMENT 

MEANING 

size 

Is an integer expression in the range 0 to 255. It 
specifies the new width. 

filenum 

Is the number under which the file was opened. 

device 

Is a string expression indicating the device that is 
to be used. Valid devices are: SCRN:, LPT1:, 
LPT2:, LPT3:, COM1:, COM2:. 


WIDTH LPRINT size 

Sets the line width at the line printer. 


WIDTH size or WIDTH ”SCRN :”,size 

Sets the screen width (Text Mode) or changes mode (Graphics Mode). 
The value given for size can be 40 or 80. If GW-BASIC is in screen 
mode 1 a value for size of 80 will change the mode to screen mode 
2; whereas a value of 40 in screen mode 2 or 3 will result in changing 
the mode to screen mode 1. 












WIDTH #filenum,size 

If the file is open, the width is immediately changed to the specified 
size . This allows the width to be changed while the file is open. 


WIDTH device,size 

The default line width for the specified device is set to size . 
The line widths of currently open files are not modified. 

Stores the new size without changing the current width, if the 
device is already open. A subsequent OPEN device FOR OUTPUT 
AS# n will use the specified value for width initially. 


Remarks 

When the WIDTH statement causes a change in the screen mode, col¬ 
ors are set to their default values. 

You should turn the function key display off when changing the win¬ 
dow width (by a KEY OFF statement), otherwise, if the width is decreas¬ 
ed, part of the old (wider) function key display may be left on the screen. 

If size is 255, the line width is ’’infinite”; that is, GW-BASIC never 
inserts a carriage return. However, the position of the cursor or the 
print head, as given by the POS or LPOS function, returns to zero after 
position 255. WIDTH 255 is the default for communications files. 

If you alter the width for a communications file, you do not modify the 
receive or the transmit buffer: GW-BASIC will insert a CR after a 
number of characters, equal to the specified size , has been receiv¬ 
ed or sent. 
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Example 

10 WIDTH ”LPT1:”, 5 

20 OPEN ”LPT1:” FOR OUTPUT AS 1 

30 PRINT #1, ”1234567890” 

35 PRINT #1 

40 WIDTH #1,6 

50 PRINT #1, ”1234567890” 

RUN 

will yield on the printer: 

12345 

67890 

123456 

7890 



Example 


SCREEN 1,0 
WIDTH 80 
WIDTH 40 


’Set Screen to Medium Res. Color Graphics. 
’Change Screen to High Res. Graphics. 
’Changes Screen back to Medium Res. 


SCREEN 0,1 ’Changes Screen to 40x25 Text Color Mode. 
WIDTH 80 ’Changes Screen to 80x25 Text Color Mode. 



Possible Errors 

If size is outside the above specified ranges, an ’’Illegal function call” 
error is returned. The previous value is retained. 


WINDOW Statement 


Defines the dimensions of the current window. (Graphics Mode only). 


WINDOW [[ SCREEN ] ( wxl , wyl )-( wx2 , wy2) ] 


Where 


SYNTAX ELEMENT 

MEANING 


(wxl,wy1) -(wx2,wy2) 

(wxl,wyl) represent the lower-left, and (wx2,wy2) 
the upper-right coordinates of the window. The 
SCREEN option inverts the y-axis of the world coor¬ 
dinates, so that (wxl, wyl) represent the upper-left, 
and (wx2, wy2) the lower-right coordinates of the 
window. 
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Characteristics 

WINDOW allows you to draw lines, graphs, or objects in space not 
bounded by the physical dimensions of the screen. This is done by 
using arbitrary programmer-defined coordinates called ’’world coor¬ 
dinates”. The world coordinates are automatically converted to screen 
coordinates. 

If no parameters are given with the WINDOW statement the world coor¬ 
dinates coincide with the screen coordinates. 


If you enter: 

NEW 

SCREEN 2 


the screen will appear as: 







Now enter: 


WINDOW (-1,-1)-(1,1) 


and the screen appears as: 



If the variant: 

WINDOW SCREEN (-1 ,-1)-(1,1) 

is executed, then the screen appears as: 
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Orientation of Axes 

If the last executed WINDOW statement specified the SCREEN op¬ 
tion, the x- and y-axes of the window have the same orientation as 
the viewport (the x-axis increasing towards the right and the y-axes 
towards the bottom); if the statement did not specify the SCREEN op¬ 
tion, the y-axis of the window increases torwards the top. Therefore, 
if the same figure is drawn twice using first just WINDOW and then 
WINDOW SCREEN, the second figure will be a reflection of the first 
figure in the x-axis. 

The following example draws a triangle pointing downwards after the 
first execution of the statement at line 1000; after the second execu¬ 
tion the triangle points upwards. 

10 SCREEN 1 
20 VIEW 
30 CLS 

40 INPUT XI ,Y1 ,X2,Y2 

50 VIEW (XI ,Y1)-(X2,Y2)„1 

60 WINDOW (-1000,-1000) - (1000,1000) 

70 GOSUB 1000 

80 WINDOW SCREEN (-1000,-1000) - (1000,1000) : GOSUB 1000 
90 END 

1000 LINE (-500,500) - (500,500) : LINE - (0,-500): 

LINE - (-500,500) : A$ = INPUT$(1) : CLS : RETURN 






Fig. 8-5 Example of the Orientation of Axes 
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Projection of Images onto the Screen 

All points drawn with graphics statements in a window (defined using 
WINDOW) are projected onto the points in the viewport defined using 
the VIEW statement. If you specify the SCREEN option in the VIEW 
statement the points drawn in the WINDOW are projected onto the 
whole screen, but only the points within the current viewport are shown 
(i.e. clipping). 

Example 1 

10 PI = 3.14159 
20 SCREEN 3: CLS: KEY OFF 
30 WINDOW (0,-1 )-(2* PI, 1) 

40 VIEW SCREEN (1,1) - (200,200)„1 
50 GOSUB 1000 

60 VIEW SCREEN (440,301) - (638,398)„1 
70 GOSUB 1000 

80 VIEW SCREEN (1,202) - (638,299)„1 

90 GOSUB 1000 

100 END 

1000 PSET (0,0) 

1010 FOR ALPHA = 0 TO 2*PI STEP PI/100 
1020 LINE - (ALPHA,SIN(ALPHA)) 

1030 NEXT 
1050 RETURN 

Draws a sinusoid, and demonstrates clipping, by defining a window 
(line 30) and viewport using the statement VIEW SCREEN (lines 40, 
60 and 80). 




r 




>v 


V. 



J 


Fig 8-6 Example 1 

By varying the areas of the window and the viewport, you change the 
relationship between the points within them, and you can obtain dif¬ 
ferent screen images from the same design. 

If you vary the areas of the window and viewport, while keeping the 
ratio between the sides constant you will obtain designs that are similar; 
if you vary the ratio the images will be distorted. 


Example 2 

5 CLS 

10 SCREEN 1 

20X1 = 10: Y1 = 10:X2 = 300: Y2 = 190 
25 VIEW 

30 VIEW (XI ,Y1) - (X2,Y2) „ 1 
40 WINDOW (-100,-100) - (100,100) 

50 R = 50 
80 PSET (R,0) 
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90 PI = 3.14159 

100 FOR ALFA = 0 TO 2* PI STEP PI/100 
110 LINE -(R*COS(ALFA), R‘SIN (ALFA)) 
120 NEXT 


The above example draws a circle, made up as a polygon with a large 
number of sides, using a LINE statement in a FOR/NEXT loop. The 
same circle drawn with a CIRCLE statement would not be distorted 
if the ratio between the sides of the viewport was varied. 



If you leave the area of the viewport unchanged and vary the area of 
the window, you can enlarge or reduce the dimensions of the image 
displayed or zoom in on a detail. 


Example 3 

10 SCREEN 3 
20 VIEW 
30 CLS 

40 VIEW (1,100) - (638,200),, 1 
50 WINDOW (-100,-100) - (100,100) 
60 GOSUB 1000 
70 A$ = INPUT$(1) 

80 CLS 

90 WINDOW (-40,-40) - (40,40) 


















100 GOSUB 1000 
110 END 

1000 LINE (-50,-30) - (50,30) 

1010 CIRCLE (0,0),20 
1020 RETURN 

This example draws a circle crossed by a straight line, and 
demonstrates the zoom facility, by defining two different windows. 









J 





Fig. 8-8 Example 3 


8-354 


GW-BASIC INTERPRETER USER GUIDE 















COMMANDS, STATEMENTS AND FUNCTIONS 


You can also enlarge and reduce images by leaving the window un¬ 
modified and varying the area of the viewport. 


Example 4 

10 SCREEN 3 : KEY OFF : CLS 
20 PI = 3.14159 
30 VIEW 
40 CLS 

50 WINDOW (-100,-100) - (100,100) 
60 VIEW (200,1) - (400,200),, 1 
70 CIRCLE (0,0) , 100 
80 PAINT (30,30) 

90 VIEW (300,201) - (400,398) „ 1 
100 CIRCLE (0,0), 100 
110 PAINT (30,30) 


This example draws a circle and paints it, showing how you can define 
more than one viewport and modify an image on the screen by vary¬ 
ing the dimensions of the viewport. 



Fig. 8-9 Example 4 

Note that no clipping takes place, because the window is not modified 
and the SCREEN option is not specified in the VIEW statement. The 
circle is not distorted because the CIRCLE statement is used. 

















WRITE Statement 


Writes data to the screen. 


WRITE [list-of-expressions] 


Where 


SYNTAX ELEMENT 

MEANING 


list-of-expressions 

Is a list of numeric and/or string expressions 
must be separated by commas. 

. They 



Characteristics 

The values of the expressions are output to the screen. If no expres¬ 
sion is indicated, a blank line is output. 


Each item displayed is separated from the last by a comma. Strings 
are delimited by quotation marks. Numeric values are displayed us¬ 
ing the same format as the PRINT statement, but they are not follow¬ 
ed by blanks. After the last item in the list is displayed, GW-BASIC 
inserts a CR LF. 
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Example 

10 A = 80:B = 90:C$ =’’THAT’S ALL” 
20 WRITE A,B,C$ 

RUN 

80, 90,’’THAT’S ALL” 

Ok 


WRITE# Statement 


Writes data to a sequential file. 


WRITE# filenum , list-of-expressions 


Where 


SYNTAX ELEMENT 

MEANING 

filenum 

Is the number under which the file was OPENed 
in ”0” mode. 

list-of-expressions 

Is a list of string or numeric expressions. They must 
be separated by commas. 
















Characteristics 


The difference between the WRITE# and PRINT# statement is that 
WRITE # inserts commas between the items as they are written to the 
file and delimits strings with quotation marks. Therefore, it is not 
necessary for the user to put explicit delimiters in the list. A CR LF se¬ 
quence is inserted after the last item in the list is written to the file. 

Example 

10 A$ =’’CAMERA” : B$ = ”93604-1” 

20 WRITE #1,A$,B$ 

Statement 20 writes the following image to disk: 

’’CAMERA”,”93604-1 ” 

A subsequent INPUT# statement, such as 
30 INPUT #1,A$,B$ 

would input ’’CAMERA” to A$ and ”93604-1” to B$. 
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A. DIFFERENCES BETWEEN THIS AND 
PREVIOUS VERSIONS 




ABOUT THIS APPENDIX 

This appendix describes the difference 
GW-BASIC and previous versions. 


CONTENTS 

INTRODUCTION A-1 

CLS STATEMENT A-1 

COLOR STATEMENT A-1 

INPUT STATEMENT A-1 

INPUT # STATEMENT A-1 

LOCATE STATEMENT A-2 

SCREEN FUNCTION A-2 

SHELL STATEMENT A-2 

VIEW PRINT STATEMENT A-2 

WIDTH STATEMENT A-3 

SCREEN SCROLLING A-3 

n SWITCH A-3 

FUNCTION KEY DISPLAY A-3 

SCREEN SCROLL A-3 


between this version of 




DIFFERENCES BETWEEN THIS AND PREVIOUS VERSIONS 


INTRODUCTION 


This appendix is provided for users of GW-BASIC who have written 
programs with versions prior to 3.20 and wish to maintain compatibili¬ 
ty with version 3.20. Certain features of GW-BASIC, such as the syn¬ 
tax of some commands and statements, are different between version 
3.20 and prior versions. Each of the differences are given below. 


CLS STATEMENT 


Version 3.20 of GW-BASIC does not support parameters with the CLS 
statement, and will return ’’Syntax Error” should one be given. 


COLOR STATEMENT 


For SCREEN 1 (Medium Resolution), version 3.20 does not support 
the XOR-ing of pixels, and, consequently, the range of values allowed 
for gforeground and tforeground is 0 to 3. 


For SCREEN 2 and SCREEN 3, version 3.20 permits the specifica¬ 
tion of one parameter, foreground, which may specify any one of the 
16 colors available as in previous versions for SCREEN 0. Only one 
foreground color can be displayed at one time. The background is 
always black. 


INPUT STATEMENT 

Version 3.20 of GW-BASIC allows the use of CTRL C to break out 
of an INPUT statement, whereas previous versions did not. 


INPUT# STATEMENT 


Version 3.20 of GW-BASIC allows CTRL Z as a character when 
reading from ”KYBD:”. Therefore, the program: 


10 OPEN ”KYBD:” 
20 INPUT # 1, A$ 
30 GOTO 20 


FOR INPUT AS 1 


can only be interrupted using CTRL BREAK. Previous versions of GW- 
BASIC interpret CTRL Z as end-of-file. 




LOCATE STATEMENT 

For version 3.20 of GW-BASIC, the parameters row and col¬ 
umn are the only parameters available in the Graphics Modes. The 
parameters cursor, start and stop are still available in Text 
Mode. The cursor is initialized to a blinking underline in Text Mode, 
and is always an unblinking square block in the Graphics Modes. 


SCREEN FUNCTION 

With version 3.20 of GW-BASIC: 

SCREEN (0, col) 
and 

SCREEN (row ,0) 
are legal and are mapped to: 

SCREEN (1, col) 
and 

SCREEN (row,1) 
respectively. 

SHELL STATEMENT 

In version 3.20 of GW-BASIC, it is not permitted to invoke GW-BASIC 
after a SHELL. 


VIEW PRINT STATEMENT 

The VIEW PRINT statement is not supported under version 3.20 of 
GW-BASIC. 
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WIDTH STATEMENT 

In version 3.20 of GW-BASIC the size parameter may only be given 
the values 40 or 80. 

SCREEN SCROLLING 

For version 3.20 of GW-BASIC screen scrolling occurs when the cur¬ 
rent cursor is below the text window. For example: 


10 KEY OFF 

20 LOCATE 25,1 : PRINT ’’Sample” 
30 GOTO 20 


scrolls lines 1 through 24 for version 3.20, but no scrolling occurs in 
prior versions. 


/I SWITCH 

For version 3.20 of GW-BASIC, static File Control Blocks is the default 
condition (the /1 switch is not supported). For versions of GW-BASIC 
prior to 3.20, static File Control Blocks were specified using the /I 
switch. 


FUNCTION KEY DISPLAY 

The function key display can only be removed using the KEY OFF state¬ 
ment with version 3.20. 


SCREEN SCROLL 

Version 3.20 of GW-BASIC will output, for non-disk I/O, an extra CR 
LF at the device width at the end of line output, and will mark the next 
field as the second field on the next line. 

This program illustrates the current differences between version 3.20 
and previous versions of GW-BASIC: 




10 CLS 

20 LOCATE 20,1 : PRINT ’’the line on which to print the 
30 LOCATE 10,80 : PRINT ”X” 


X”; 



When version 3.20 of GW-BASIC finds that the end-of-screen has been 
reached, it outputs an extra CR LF in addition to the one which 
follows the PRINT ”X”. Thus, the output takes the form of the printed 
line, followed by a blank line, followed by ”Ok”. For previous versions 
of GW-BASIC, there is no intervening blank line. 
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B. MATHEMATICAL FUNCTIONS 



ABOUT THIS APPENDIX 


This appendix describes how to calculate commonly used mathematical 
functions that are not intrinsic to GW-BASIC. 




MATHEMATICAL FUNCTIONS 


The following shows how to express commonly used mathematical 
functions using those functions intrinsic to GW-BASIC. 




FUNCTION 

GW-BASIC EQUIVALENT 

SECANT 

SEC(x) = 1/COS(x) 
when x< >1.570796 

COSECANT 

CSC(x) = 1/SIN(x) 
when x< >0 

COTANGENT 

COT(x) = 1/TAN(x) 
when x< >0 

INVERSE SINE 

ARCSIN(x) = ATN(x/SQR(1 -x * x)) 

INVERSE COSINE 

ARCCOS(x) = 1,570796-ATN(x/SQR(1 -x *x)) 
when ABS(x) < 1 

INVERSE SECANT 

ARCSEC(x) = ATN(SQR(x*x-1)) 

+ SGN(SGN(x)-1)*1.570796 
when ABS(x) > = 1 

INVERSECOSECANT 

ARCCSC(x) = ATN(1 /SQR(x * x-1)) 

+ (SGN(x)-1)* 1.570796 
when ABS(x)>1 

INVERSE 

COTANGENT 

ARCCOT(x) = 1.570796-ATN(x) 

HYPERBOLIC SINE 

SINH(x) = (EXP(x)-EXP(-x))/2 

HYPERBOLIC 

COSINE 

COSH(x) = (EXP(x) + EXP(-x))/2 

HYPERBOLIC 

TANGENT 

TANH(x) = (EXP(x)-EXP(-x))/ (EXP(x) + EXP(-x)) 

HYPERBOLIC 

SECANT 

SECH(x) = 2/(EXP(x) + EXP(-x)) 

HYPERBOLIC 

COSECANT 

CSCH(x) = 2/(EXP(x)-EXP(-x)) 
when x< >0 

► 









FUNCTION 


GW-BASIC EQUIVALENT 


HYPERBOLIC 

COTANGENT 


COTH(x) = (EXP(x) + EXP(-x))/ (EXP(x)-EXP(-x)) 
when x< >0 


INVERSE 

HYPERBOLIC SINE 


ARCSINH(x) = LOG(x + SQR(x*x + 1)) 


INVERSE 

HYPERBOLIC 

COSINE 


ARCCOSH(x) = LOG(x + SQR(x*x-1)) 
when x> = 1 


INVERSE 

HYPERBOLIC 

TANGENT 


ARCTANH(x) = LOG((1 + x)/(1-x))/2 
when ABS(x)< 1 


INVERSE 

HYPERBOLIC 

SECANT 


ARCSECH(x) = LOG((SQR(1-x*x) + 1)/x) 
when 0<x< = 1 


INVERSE 

HYPERBOLIC 

COSECANT 


ARCCSCH(x) = LOG((SG N(x) * SQR(x * x + 1) + 1 )/x) 
when x>0 


INVERSE 

HYPERBOLIC 

COTANGENT 


ARCCOTH(x) = LOG((x + 1 )/(x-1 ))/2 
when ABS(x)>1 


LOGARITHM TO 
BASE ’a’ 


LOGA(x) = LOG(x)/LOG(a) 
when a>0 and x>0 


You can define a derived mathematical function in your program by 
use of a DEF FN statement, to avoid coding the formula each time 
you need it. 


Note that both ’x’ and ’a’ can be any numeric constant, variable, ar¬ 
ray element, function or expression. Any values of ’x’ or ’a’ that would 
cause error messages are specified. 
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C. ASCII CHARACTER CODES 




ABOUT THIS APPENDIX 

This appendix provides a table of ASCII characters. 



ASCII CHARACTER CODES 


This table shows the decimal and hexadecimal codes and the sym¬ 
bols displayed for the 256 elements of the extended ASCII character 
set. 


DEC: 

HEX 

CHARACTER 

DEC: 

HEX 

CHARACTER 

DEC: 

HEX 

CHARACTER 

DEC: 

HEX 

CHARACTER 

000 

00 

InTu (nud 

016 

10 

► (DLE) 

032 

20 

(SPACE) (SP) 

048 

30 

0 

001 

01 

© (SOH) 

017 

11 

** (DC1) 

033 

21 

! 

049 

31 

1 

002 

02 

£ (STX) 

018 

12 

\ 0C2) 

034 

22 

yy 

050 

32 

2 

003 

03 

V (ETX) 

019 

13 

!! (DC3) 

035 

23 

# 

051 

33 

3 

004 

04 

♦ (EOT) 

020 

14 

TT (DC4) 

036 

24 

$ 

052 

34 

4 

005 

05 

♦ (ENQ) 

021 

15 

§ (NAK) 

037 

25 

% 

053 

35 

5 

006 

06 

4 (ACK) 

022 

16 

■■ (SYN) 

038 

26 

& 

054 

36 

6 

007 

07 

• (BEL) 

023 

17 

I (ETB) 

039 

27 

y 

055 

37 

7 

008 

08 

Q (BS) 

024 

18 

t (CAN) 

040 

28 

( 

056 

38 

8 

009 

09 

O («T) 

025 

19 

1 (EM) 

041 

29 

) 

057 

39 

9 

010 

0A 

SI (LF) 

026 

1A 

— (SUB) 

042 

2A 

* 

058 

3A 

: 

Oil 

0B 

Cf (vt) 

027 

IB 

— (ESC) 

043 

2B 

+ 

059 

3B 

y 

012 

OC 

9 <FF) 

028 

1C 

1— (FS) 

044 

2C 

y 

060 

3C 

< 

013 

OD 

(CR) 

029 

ID 

— (GS) 

045 

2D 

— 

061 

3D 

= 

014 

OE 

j (SO) 

030 

IE 

A (RS) 

046 

2E 

. 

062 

3E 

> 

015 

OF 

(SI) 

031 

IF 

▼ (US) 

047 

2F 

/ 

063 

3F 

? 
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DEC: 

HEX 

CHARACTER 

DEC: 

HEX 

CHARACTER 

DEC: 

HEX 

CHARACTER 

DEC: 

HEX 

CHARACTER 

064 

40 

@ 

080 

50 

P 

096 

60 

i 

112 

70 

P 

065 

41 

A 

081 

51 

Q 

097 

61 

a 

113 

71 

q 

066 

42 

B 

082 

52 

R 

098 

62 

b 

114 

72 

r 

067 

43 

C 

083 

53 

S 

099 

63 

c 

115 

73 

s 

068 

44 

D 

084 

54 

T 

100 

64 

d 

116 

74 

t 

069 

45 

E 

085 

55 

U 

101 

65 

e 

117 

75 

u 

070 

46 

F 

086 

56 

V 

102 

66 

f 

118 

76 

V 

071 

47 

G 

087 

57 

W 

103 

67 

g 

119 

77 

w 

072 

48 

H 

088 

58 

X 

104 

68 

h 

120 

78 

X 

073 

49 

I 

089 

59 

Y 

105 

69 

i 

121 

79 

y 

074 

4A 

J 

090 

5A 

Z 

106 

6A 

j 

122 

7A 

z 

075 

4B 

K 

091 

5B 

[ 

107 

6B 

k 

123 

7B 

( 

076 

4C 

L 

092 

5C 

\ 

108 

6C 

1 

124 

7C 

1 

1 

077 

4D 

M 

093 

5D 

] 

109 

6D 

m 

125 

7D 

) 

078 

4E 

N 

094 

5E 

A 

110 

6E 

n 

126 

7E 

- 

079 

4F 

O 

095 

5F 

— 

111 

6F 

o 

127 

7F 

A (DEL) 


Tab. C-1 Extended ASCII Character Set (cont.) 
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ASCII CHARACTER CODES 


dec 

HEX 

CHARACTER 

DEC 

HEX 

CHARACTER 

DEC 

HEX 

CHARACTER 

DEC 

HEX 

CHARACTER 

128 

80 

C 

144 

90 

E 

160 

AO 

a 

176 

BO 


129 

81 

U 

145 

91 

ae 

161 

A1 

i 

177 

B1 


130 

82 

e 

146 

92 

PE 

162 

A2 

6 

178 

B2 

■ 

131 

83 

a 

147 

93 

6 

163 

A3 

u 

179 

B3 

1 

132 

84 

a 

148 

94 

6 

164 

A4 

n 

180 

B4 

H 

133 

85 

a 

149 

95 

6 

165 

A5 

N 

181 

B5 

=\ 

134 

86 

a 

150 

96 

u 

166 

A6 

a 

182 

B6 

HI 

135 

87 

9 

151 

97 

u 

167 

A7 

o 

183 

B7 


136 

88 

e 

152 

98 

y 

168 

A8 

i 

184 

B8 

=\ 

137 

89 

e 

153 

99 

6 

169 

A9 

i - 

185 

B9 

HI 

138 

8A 

e 

154 

9A 

u 

170 

AA 

"i 

186 

BA 

II 

139 

8B 

i 

155 

9B 

$ 

171 

AB 

1/2 

187 

BB 

=il 

140 

8C 

i 

156 

9C 

£ 

172 

AC 

1/4 

188 

BC 

J 

141 

8D 

i 

157 

9D 

1 

T 

173 

AD 

i 

189 

BD 

J 

142 

8E 

A 

158 

9E 

Pt 

174 

AE 

« 

190 

BE 

=1 

143 

8F 

A 

159 

9F 

f 

175 

AF 

» 

191 

BF 

n 1 
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DEC 

HEX 

CHARACTER 

DEC 

HEX 

CHARACTER 

DEC 

HEX 

CHARACTER 

DEC 

HEX 

CHARACTER 

192 

CO 

L 

208 

DO 

JL 

224 

EO 

a 

240 

FO 

= 

193 

Cl 

_L 

209 

D1 

T 

225 

El 

P 

241 

FI 

+ 

194 

C2 

T 

210 

D2 

IT 

226 

E2 

r 

242 

F2 

> 

195 

C3 

h 

211 

D3 

IL 

227 

E3 

n 

243 

F3 

< 

196 

C4 

— 

212 

D4 

i= 

228 

E4 

2 

244 

F4 

r 

197 

C5 

+ 

213 

D5 

r 

229 

E5 

a 

245 

F5 

j 

198 

C6 

h 

214 

D6 

r 

230 

E6 

n 

246 

F6 


199 

C7 

b 

215 

D7 

+ 

231 

E7 

I 

247 

F7 

• 

200 

C8 

L 

216 

D8 

4= 

232 

E8 

<t> 

248 

F8 

o 

201 

C9 

r 

217 

D9 

j 

233 

E9 

■©■ 

249 

F9 

• 

202 

CA 

JL 

218 

DA 

r 

234 

EA 

Q 

250 

FA 

• 

203 

CB 

T 

219 

DB 

■ 

235 

EB 

6 

251 

FB 

vT 

204 

CC 

11= 

220 

DC 

« 

236 

EC 

00 

252 

FC 

n 

205 

CD 

= 

221 

DD 

1 

237 

ED 

0 

253 

FD 

2 

206 

CE 

JL 

nr 

222 

DE 

1 

238 

EE 

E 

254 

FE 

1 

207 

CF 

=1, 

223 

DF 

■ 

239 

EF 

n 

255 

FF 

(SPACE) (SP) 


Tab. C-1 Extended ASCII Character Set (cont.) 
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D. CONVERSION TABLES 




ABOUT THIS APPENDIX 


This appendix shows the conversion tables for hexadecimal to decimal 
and for decimal to binary, octal and hexadecimal. 





CONVERSION TABLES 


HEX 

DEC 

HEX 

DEC 

HEX 

DEC 

HEX 

DEC 

0 

0 

0 

0 

0 

0 

0 

0 

1 

4096 

1 

256 

1 

16 

1 

1 

2 

8192 

2 

512 

2 

32 

2 

2 

3 

12288 

3 

768 

3 

48 

3 

3 

4 

16384 

4 

1024 

4 

64 

4 

4 

5 

20480 

5 

1280 

5 

80 

5 

5 

6 

24576 

6 

1536 

6 

96 

6 

6 

7 

28672 

7 

1792 

7 

112 

7 

7 

8 

32768 

8 

2048 

8 

128 

8 

8 

9 

36864 

9 

2304 

9 

144 

9 

9 

A 

40960 

A 

2560 

A 

160 

A 

10 

B 

45056 

B 

2816 

B 

176 

B 

11 

C 

49152 

C 

3072 

C 

192 

C 

12 

D 

53248 

D 

3328 

D 

208 

D 

13 

E 

57344 

E 

3584 

E 

224 

E 

14 

F 

61440 

F 

3840 

F 

240 

F 

15 

4 

3 

2 

1 

BYTE 

BYTE 


Tab. D-1 Conversion Table for Hexadecimal to Decimal 
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DECIMAL 

BINARY 

OCTAL 

HEX 

0 

0000 

0 

0 

1 

0001 

1 

1 

2 

0010 

2 

2 

3 

0011 

3 

3 

4 

0100 

4 

4 

5 

0101 

5 

5 

6 

0110 

6 

6 

7 

0111 

7 

7 

8 

1000 

10 

8 

9 

1001 

11 

9 

10 

1010 

12 

A 

11 

1011 

13 

B 

12 

1100 

14 

C 

13 

1101 

15 

D 

14 

1110 

16 

E 

15 

1111 

17 

F 

16 

10000 

20 

10 


Tab. D-2 Conversion Table for Decimal, Binary, Octal and Hexadecimal 
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E. CONVERSION OF PROGRAMS 
TO GW-BASIC 






ABOUT THIS APPENDIX 


This appendix outlines the criteria to be followed in order to convert 
programs written in other BASICS to GW-BASIC. 


CONTENTS 


INTRODUCTION 

E-1 

STRING DIMENSIONING 

E-1 

LENGTH OF STRINGS 

E-1 

SUBSTRINGS 

E-1 

CONCATENATION 

E-2 

MAT FUNCTIONS 

E-2 

MULTIPLE 

ASSIGNMENTS 

E-2 

MULTIPLE 

STATEMENTS 

E-3 

PEEKS AND POKES 

E-3 

IF...THEN[...ELSE] 

E-3 

FILE I/O 

E-3 

GRAPHICS 

E-4 






CONVERSION OF PROGRAMS TO GW-BASIC 


INTRODUCTION 

The GW-BASIC languages bears a similarity to many BASICs. Your 
personal computer will support programs written for an extensive varie¬ 
ty of microcomputers. For programs written in a BASIC other than GW- 
BASIC, some minor adjustments may be necessary before running 
them. This appendix highlights some specific areas to examine when 
converting programs. 


STRING DIMENSIONING 


LENGTH OF STRINGS 

GW-BASIC strings are of variable lengths. Therefore, all statements 
that declare the length of strings should be deleted. For example, in 
a statement which dimensions a string array for ’J’ elements of lengths 
T such as: 

DIM A$(I,J) 

the conversion for GW-BASIC would be: 

DIM A$(J) 

SUBSTRINGS 

In GW-BASIC the following functions are used to take substrings of 
strings: 

LEFT$ 

MID$ 

RIGHTS 

Other forms, such as: 

A$(l) (to access the Ith character in A$) or, 

A$(I,J) (to take a substring of A$ from position I to J) should be 
changed as follows: 







Other BASICS 


GW-BASIC 


X$ = A$(I) 
X$ = A$(I,J) 


X$ = MID$(A$,I,1) 

X$ = MID$(A$,I,J-I +1) 


If the substring reference is on the left side of an assignment and X$ 
is used to replace characters in A$, then the conversion should be car¬ 
ried out as follows: 


Other BASICS 


GW-BASIC 


A$(l) = X$ 
A$(I,J) = X$ 


MID$(A$,I,1) = X$ 
MID$(A$,I,J-I +1) = X$ 


CONCATENATION 

GW-BASIC uses a plus (+) sign to denote string concatenation. Other 
BASICS use a comma (,) or an ampersand (&) which should be altered 
accordingly. 


MAT FUNCTIONS 

Some BASICS incorporate MAT functions for array handling. To con¬ 
vert a program which uses these functions to the GW-BASIC environ¬ 
ment, it is necessary to rewrite the program including FOR...NEXT 
loops. 


MULTIPLE ASSIGNMENTS 

Some BASICs allow the following syntax: 

10 LET D = E = 0 

to set D and E equal to zero. GW-BASIC interprets the second equal 
sign as a logical operator and sets D equal to -1 if E was equal to 0. 
This statement should therefore be broken up into two assignment 
statements as follows: 

10 D = 0:E = 0 
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MULTIPLE STATEMENTS 

Multiple statements on a GW-BASIC line must always be separated 
by colons (:), unlike some other BASICS which use a backslash (\) 
instead. 

PEEKS AND POKES 

The execution of programs containig PEEK and POKE instructions may 
vary from machine to machine. It is therefore necessary to analyse 
the purpose of these instructions in other BASIC programs before 
translating the same functions into GW-BASIC. 


IF...THEN...[ELSE...] 

Not all BASICS feature the optional ELSE clause which is performed 
in the event of a test proving false. 

For example, a BASIC statement may originally be: 

10 IF D = E THEN 30 

20 PRINT ’’NOT EQUAL” : GOTO 40 

30 PRINT ’’EQUAL” 

40 REM CONTINUE 

The above statement sequence will work correctly, but it may be op¬ 
timized in GW-BASIC as follows: 

10 IF D = E THEN PRINT ’’EQUAL” ELSE PRINT ’’NOT EQUAL” 
20 REM CONTINUE 


FILE I/O 

In some BASICs, the I/O to disk may differ from GW-BASIC. Refer to 
Chapter 4 for more information. 







GRAPHICS 


Selecting screen attributes and drawing objects on the screen can vary 
from BASIC to BASIC. Refer to Chapter 5 for more information on 
graphics. 
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F. MEMORY MANAGEMENT 



ABOUT THIS APPENDIX 


This appendix contains specific technical information pertaining to 
GW-BASIC. 

It includes: 

• How GW-BASIC allocates variables 

• Internal representation of floating point numbers 

• Memory map 

• The File Control Block Structure 


CONTENTS 


ALLOCATION OF F-1 

VARIABLES 

INTERNAL F-3 

REPRESENTATION OF 
FLOATING POINT 
NUMBERS 

FILE CONTROL BLOCK F-4 


MEMORY MAP 
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MEMORY MANAGEMENT 




ALLOCATION OF VARIABLES 

Each variable defined is associated with a record allocated in the GW- 
BASIC Data Segment. The record is made up of a field structure, each 
field contains an attribute of the variable (type, name, string descriptor) 
or its value. A record associated with a numeric variable contains its 
value, while a record associated with a string variable contains a field 
(the string descriptor) which points to the address, in the String Space, 
in which the value of the variable is stored. 

The following table shows the way in which a numeric or string variable 
is allocated in memory. In particular, the first column gives the offset 
of the field with respect to the start address of the record, the second 
column gives the length (in bytes), the third column the contents, and 
the fourth provides other information. 


OFFSET 

LENGTH 

DESCRIPTION 

COMMENTS 

0 

1 

Type 

The value of the variable type is: 

2 (integers) 

3 (strings) 

4 (single-precision numbers) 

5 (double-precision numbers) 


Tab. F-1 Allocation of Variables 










OFFSET 

LENGTH 

DESCRIPTION 

COMMENTS 

1 

3 to 
n + 3 

Name 

- Bytes 1 and 2 contain the first 2 
characters of the name 

- Byte 3 contains a number in¬ 
dicating how many more 
characters are in the name 

- Bytes 4 to n contain the additional 
characters of the name. 

Three bytes are reserved for the 
name of the variable, even if the 
name is only one or two 
characters long. In this case the 
data (or string descriptor) begins 
with an offset of 4. 

4 + n 

2 

Integer Value 

Integers are stored low byte first, 
then high byte 


3 

String 

Descriptor 

- First byte contains the string 
length (0-255) 

- Second byte is the low byte of the 
offset to the start address of GW- 
BASIC’s data segment 

- Third byte is the high byte of the 
offset to the start address of 
GW-BASIC’s data segment 


4 

Single 

Precision Value 

In floating point format 


8 

Double 

Precision Value 

In floating point format 


Tab. F-1 Allocation of Variables (cont.) 
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INTERNAL REPRESENTATION OF FLOATING POINT 
NUMBERS 

The following section describes the internal representation of numbers 
in GW-BASIC. 


Single Precision - 24 bit mantissa 


I 0 111 2 131 

I loman I ISIhimanl exp I 

where: 

loman = the low mantissa 
S = the sign 

himan= the high mantissa 
exp= the exponent 
man= himan:....:loman 

If exp = 0, then number = 0 

If exp< >0, then the mantissa is normalized and 
number = sign * .1 man * 2 ** (exp -80h) 

That is, in single precision (hex notation - bytes low to high) 

00000080 = .5 
00008080 = -.5 


Double Precision - 56 bit mantissa 

I 0 I 1 I 2 I 3 I 4 I 5 I 6 171 


I loman I I I I I ISIhimanl exp I 








FILE CONTROL BLOCK 

The following table shows the information held in the File Control Block 
(FCB). The offsets are with respect to the address returned by the 
VARPTR function. GW-BASIC’s File Control Block in different from that 
of MS-DOS. 


OFFSET 

LENGTH 

NAME 

MEANING 

0 

1 

Mode 

The mode in which 
file was opened: 

1 - Input 

2 - Output 

4 - Random 

Access 

16 - Append 

32 - Reserved 

128 - Reserved 

1 

38 

FCB 

MS-DOS File Control 
Block. 

39 

2 

CURLOC 

Number of sectors 
written to or read (for 
sequential files); 
number of last record 
written to or read +1 
(for random access 
files). 

41 

1 

ORNOFS 

Number of bytes per 
sector 


Tab. F-2 File Control Block 
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OFFSET 

LENGTH 

NAME 

MEANING 

42 

1 

NMLOFS 

Number of bytes left 
in INPUT buffer 

43 

3 

- 

Reserved 

46 

1 

DEVICE 

Number of the device: 
0-9 Disk Drives 

(A: - J:) 

255 Keyboard 

254 SCRN: 

253 LPT1: 

252 CAS1: 

251 COM1: 

250 COM2: 

249 LPT2: 

248 LPT3: 

47 

1 

WIDTH 

Line width of the 
device 

48 

1 

POS 

Buffer position for 
PRINT# 

49 

1 

FLAGS 

Internal use during 
LOAD/SAVE. Not us¬ 
ed for file data 

50 

1 

OUTPOS 

Output position used 
in tabulation 
operations 


Tab. F-2 File Control Block (cont.) 

















OFFSET 

LENGTH 

NAME 

MEANING 

51 

128 

BUFFER 

Data Buffers, used for 
the transfer of data 
between MS-DOS 
and GW-BASIC. This 
offset must be used 
for examining data in 
sequential I/O. 

179 

2 

VRECL 

Record length for ran¬ 
dom access files, set 
in the OPEN state¬ 
ment. Default value: 
128. 

181 

2 

PHYREC 

Number of current 
physical record 

183 

2 

LOGREC 

Number of current 
logical record 

185 

1 

- 

Reserved 

186 

2 

OUTPOS 

Position used by 
PRINT#, INPUT# 
and WRITE#. Only 
used for disk files. 


Tab. F-2 File Control Block (cont.) 
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OFFSET 

LENGTH 

NAME 

MEANING 

188 

n 

FIELD 

Current Buffer Field. 

Its length, in bytes, is 
set by the /S: switch in 
the GWBASIC Com¬ 
mand. VRECL bytes 
are transferred bet¬ 
ween BUFFER and 
FIELD in I/O opera¬ 
tions. This offset must 
be used to examine 
the data of a I/O 
operation for random 
access files. 


Tab F-2 File Control Block (cont.) 









MEMORY MAP 

The map below illustrates the system memory structure. 


MS-DOS 

Segment 

System interrupt 
vectors, variables, 

etc 


MS-DOS 

(approximately 12 K) 


MS-DOS workarea 

GW-BASIC 

Code 

Segment 

GW-BASIC 

code 

(approximately 60 K) 

COM Buffer 

Segment 

GW-BASIC 

Communications buffer(s) 

GW-BASIC 

Data Segment 

Interpreter 

Workarea 

(approximately 3 K) 


GW-BASIC Program 


Scalar Variables 


Arrays 


String Space 


GW-BASIC stack 

128 Bytes 

(or set by the CLEAR 
command) 


-System Segment 

System memory, screen memory 


ROM 


Fig. F-3 Memory Map 
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MEMORY MANAGEMENT 


In the GW-BASIC workarea there are some variables available to the user, 
which may be accessed via PEEK or POKE. These variables are not 
at the actual addresses specified: PEEK and POKE map the specified 
addresses to the actual locations. 


The start address of the GW-BASIC Data Segment may be obtained by 
examining the word at absolute location 0:51 OH. (This is an actual 
address). 

This information is not required to execute PEEKs and POKEs; a DEF 
SEG statement sets up the right segment. In this case, the following loca¬ 
tions are of significance: 


ADDRESS 

(Decimal) 

OFFSET 

(Hex) 

MEANING 

46 

2EH 

Current line number 

839 

347H 

Current Error line 
number 

48 

30H 

Offset of start of Program 

856 

358H 

Offset of start of 

Variables 

106 

6AH 

Keyboard buffer 
PEEK/POKE location 




F-9 








The first four locations are word variables which are mapped to the given 
addresses when the PEEK function and POKE statements are used. Note 
that these are 2-byte variables; thus, execution of the program line 


1234 X = PEEK(46) + 256 * PEEK(47) 


sets X = to the value 1234, which is the current line number. 


POKE-ing a 0 to the location 106 (decimal) will clear the keyboard buf¬ 
fer. Any other value POKE-ed to this address will have no effect. 


PEEK(106) will return a 0 if no keyboard characters are available, 
a 1 if any are available. 


and 
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G. GLOSSARY 



ABOUT THIS APPENDIX 


This appendix lists a glossary oriented to GW-BASIC special words 
and definitions used throughout this manual. 




GLOSSARY 



absolute coordinates: In graphics, the x and y coordinates of a point 
on the screen with reference to the origin of the specified coordinate 
system. 

access mode: A technique that is used to address a specific record 
in a file. 

active page: The section of the screen buffer to be written to by out¬ 
put statements to the screen. It may be different from the visual page 
in Text Mode. 

address: Location in storage. 

animation: The technique of displaying a sequence of images so that 
you can see the objects moving on the screen. 

argument: A value that is passed from the main program to a func¬ 
tion or a subroutine 

array: A collection of variables of the same type under one name. You 
can distinguish them by the value(s) of one or more subscripts. 

array element: An element of an array. It is a variable whose name 
coincides with the name of the array and is followed by one or more 
subscripts in parenthesis. They specify the position of the array ele¬ 
ment within the array. 

aspect ratio: A fraction used to specify how many pixels are needed 
along the two axis in order to display lines of the same length. The 
numerator specifies the number along the y-axis and the denominator 
the number along the x-axis. 

asynchronous transmission: A method of transmitting data in which 
each transmitted character is preceded by a start bit and followed by 
a stop bit, thus permitting the interval between characters to vary. 

background color: The color of the area which surrounds the sub¬ 
ject. In particular, the color of the screen surrounding a character 
(character background color) or the color displayed when a graphics 
viewport is cleared (graphics background color). 

baud rate: The transmission rate which is in effect synonymous with 
signal events (usually bits) per second. 







bit map: An area in memory, the bits of which are associated with 
points on the screen. If only one bit is associated with one point on 
the screen, then you can display two colors (black or white); it two bits 
are associated to one point on the screen you can display four colors. 

boolean value: A numeric value that GW-BASIC uses (in a statement 
or a command) as a ’’true” or ’’false” condition to direct program flow 
or for other purposes. 

boot: The loading of the operating system into memory, 
built-in function: See intrinsic function. 

call: The branching or transfer of control to a specified subroutine. 

carriage return character (CR): A character that moves the cursor or 
the print head position to the beginning of the next line. Entering CR 
when you finish typing a GW-BASIC line, passes the line to GW-BASIC 
for processing. 

clipping: The graphics statements use line clipping, i.e. lines that cross 
the screen or viewport are ’’clipped” at the edges of the viewing area. 

color code: A number in the range 0 to 15 that identifies a color. 

color number: In graphics, a number, in the range 0 to 3, that selects 
the actual color from a palette. 

command level: GW-BASIC is at command level when Ok appears 
on the screen, i.e. when it is waiting for the user to enter an immediate 
or program line. 

comment: A remark inserted in a program for documentation pur¬ 
poses. In GW-BASIC, a comment may be entered by REM or a single 
quote (’) followed by the comment string. The single quote (’) also 
allows the insertion of comments at the end of a GW-BASIC line. 

concatenation: The operation that joins a string to another string by 
the use of the operator ” + 

constant: A value which does not change during program execution. 
A constant may be a string or a numeric constant. In the latter case 
it may be an integer, a single-precision or a double-precision number. 
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GLOSSARY 


coordinates: Numbers that are used to specify a location on the 
screen. They may be text coordinates to identify a character or the 
cursor (expressed in terms of rows and columns) or graphics coor¬ 
dinates to identify a pixel (expressed as x and y Cartesian coordinates) 

current directory: The directory you are working on. You may change 
the current directory by the CHDIR command. Just after formatting 
a disk the Root directory is the current directory. 

current line: The line you are working on, or the line you have just 
entered, or the line where an error has occurred. 

current point: See the ’’last referenced point”. 

current program: The program currently in memory. 

current segment: The memory segment defined by the last DEF SEG 
statement that has been executed, or the GW-BASIC Data Segment. 

current viewport: The viewport you are working on. To change 
viewport you must use a VIEW statement. 

cursor: A movable marker which indicates a screen position. There 
are three types of cursor: the overwrite, the insert and the user cur¬ 
sor. The shape and blinkrate of the overwrite and user cursors are pro¬ 
grammable. The user cursor is not visible but can be made visible using 
the LOCATE Statement. 

debug: To locate and correct errors in a program. 

default: The value of a parameter that will be assumed by the system, 
if no value is entered by the user. 

default drive: When a file specifier or a pathname is given, the default 
drive is the one that was the default in MS-DOS before GW-BASIC 
was invoked. At initialization the default drive is the drive from which 
MS-DOS is loaded. The default drive may only be changed in MS-DOS 
entering the driver specifier (A:, B:, C:, etc ...) either before the name 
of an MS-DOS command, or alone. 

destination variable: The variable to the left of the equal sign in an 
assignment statement. 






device: A peripheral. Examples of devices are: the printer, the 
keyboard, the screen, an I/O port, etc. 


direct access: File access method by which each record is directly 
addressable. The ability to read or write information at any location 
within a storage device. 

direct line: See ’’immediate line”. 

direct mode: See ’’immediate mode”. 

directory: The directory contains the names of files on the disk, along 
with information that tells MS-DOS where to find the file. 


disk: Is a generic term to specify either a hard-disk or a diskette, 
diskette: A 5 1/4 inch mini floppy disk. 


double precision: This is the maximum precision GW-BASIC can han¬ 
dle. If a number contains more than 7 digits it is a double-precision 
number. 


drive: Synonymous with disk drive. May be specified by A: (first diskette 
drive), B: (second diskette drive), C: (hard-disk drive), etc.. 

dummy argument: A fictitious parameter in a function or statement 
or command. A value must be entered, but it is ignored by GW-BASIC. 

edit: To modify a GW-BASIC line displayed on the screen. 

end of file (EOF): A ’’marker” following the last record in a file. 

error trapping: When an error occurs, the control of the program may 
be automatically directed to a specified error handling routine, rather 
than to the standard routine. A user error handling routine should check 
for all the particular errors the user wishes to recover from, and in¬ 
dicate what to do in each case. 

event trapping: When a certain event occurs, the control of the pro¬ 
gram may be automatically directed to a specified trapping routine. 
The trap routine, after servicing the event, executes a RETURN state¬ 
ment that causes the program to resume execution. The events that 
can be trapped are receipt of characters from an RS-232-C port, detec¬ 
tion of certain keystrokes, time passage, and emptying of the 
background music queue. 
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expression: An algorithm returning a"single numeric value (numeric, 
relational or logical expressions) or a concatenation of strings return¬ 
ing a string value (string expression). 

extended code: The extended ASCII code is returned by the INKEY$ 
function if a key (or key combination) is entered, that cannot be 
associated with a standard ASCII code (See the ’’MS-DOS User 
Guide”). 

field: The area in a record, used to allocate a particular data item. 

file: A collection of records. The records of a file may be accessed 
by GW-BASIC sequentially (one after the other) or randomly (by record 
number). 

filename: The name assigned to a file. It may include an extension 
of three characters separated from the filename with a period. (BAS, 
BAT, COM, or EXE extensions have special meanings.) 

File number: A number, in the range 1 to 255, associated with a file 
when it is opened. Used by all I/O statements to refer to a file. 

file specifier: Unique file identifier. It includes the filename, possibly 
preceded by a device specifier (A:, B:, C:,...). If no device is specified 
the current drive is assumed. 

fixed-length records: Enumerable elements in a file each of which 
has the same length. For example, in GW-BASIC, the records of a ran¬ 
dom file have the same length. 

floppy disk: Synonymous with diskette. 

foreground color: The color of a character (character foreground col¬ 
or), or the color used to draw pictures when no color parameter is 
specified in a graphics statement (graphics foreground color). 

full duplex: A communication system permitting simultaneous opera¬ 
tion in both directions. 

function: An algorithm returning a single value. A function can be a 
user or an intrinsic function. It can be called simply by stating its name, 
followed (in parentheses) by one or more ’’arguments” representing 
the values that the function parameters are to assume. 




function key: A key to which the user can assign a special meaning. 
Typing the key you may generate any character string. Some function 
keys may already be assigned by the system at initialization. 

graphics viewport: See viewport 

GW-BASIC: In this manual refers only to Microsoft GW-BASIC Inter¬ 
preter version 2.0 as implemented on the Olivetti Personal Computers. 

half duplex: A communication system permitting operation in either 
direction, but not simultaneously. 

hard disk: A rigid disk. In this manual, referring to a 5 1/4 inch Win¬ 
chester type disk. 

immediate line: A GW-BASIC line which begins with a letter. It is ex¬ 
ecuted as soon as you press CR. 

immediate mode: This mode is used to immediately enter and ex¬ 
ecute a GW-BASIC line. 

indirect line: See ’’program line” 

indirect mode: See ’’program mode” 

interrupt: The suspension of a process, such as the execution of a 
program, caused by an event external to that process, and performed 
in such a way that the process can be resumed. 

intrinsic function: a function that the user may call without defining 
it as it is an integral part of GW-BASIC (e.g. SIN(x)). 

keyword: A word used to identify an action to be performed by a state¬ 
ment, a function, or a command. A keyword is a reserved word, i.e. 
it may not be used to name a variable. 

last referenced point: In graphics, the last referenced point may be 
used for relative coordinates. 

line: A GW-BASIC line may begin with a line number (if it is a pro¬ 
gram line) or with a letter (if it is an immediate line). The line may con¬ 
tain one or more GW-BASIC statements or commands (separated by 
colons) and may be up to 255 characters long. 
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line folding: The continuation of a logical line on a subsequent physical 
line, so that the line can be modified by (insertion or deletion) without 
losing any other characters on that line. 

loop: The repeated execution of a series of statements for a fixed 
number of times. 

machine infinity: The largest value that can be represented in GW- 
BASIC number format. 

matrix: See array. 

MS-DOS: Microsoft- Disk Operating System. In this manual, refers only 
to the Olivetti Personal Computer Disk Operating System. 

nest: To embed a FOR/NEXT or WHILE/WEND block into a larger 
FOR/NEXT or WHILE/WEND block. Also to call a subroutine from 
another subroutine. 

null string: A string that does not contain any characters, i.e., of zero 
length. (It is represented as ””). 

numeric expression: An expression whose evaluation returns a 
numeric value. This may be an integer, a single precision or a double 
precision value. 

numeric keypad: The section on the right of the keyboard dedicated 
to numbers, arithmetic symbols, cursor movement keys, and some con¬ 
trol characters. 

numeric variable: A simple variable or array element whose value is 
numeric; i.e. an integer, single precision or double precision variable. 

offset: The number of bytes from a starting point in memory to some 
other point. In GW-BASIC a memory address may be specified as an 
offset within a memory segment. 

option switch: One of the options in the GWBASIC command line 
specified with a slash (/) followed by a character or by a character and 
a colon. 




overflow: In an arithmetic operation, the generation of a quantity 
beyond the capacity of a register or location which is to receive the 
result. If an overflow occurs, GW-BASIC displays an error message. 

overlay: Programs too large for memory can be divided into logical 
segments (or overlays). Overlays are loaded into memory and executed 
and then erased to allow the transfer of another overlay. 

palette: In graphics, a group of foreground colors in color number 
order. 

parameter: Variable information in a statement, function, or command 
that the user has to supply. Used interchangeably with ’’argument”. 
An ’’actual parameter” is a value that is substituted for a ’’formal 
parameter” in a given procedure or function when it is invoked. 

pathname: A sequence of directory names separated by backslashes 
(\). The last element of a pathname may be a directory or a file name. 
In the former case the pathname is used to specify a directory, in the 
latter case to specify a file. The first element of a pathname may be 
a device specifier. 

pixel: Contraction of ’’picture element”, i.e. a graphics ’’point” ad¬ 
dressable on the screen by its (x,y) coordinates. 

program mode: This mode is used to enter into memory a GW-BASIC 
program line. To tell GW-BASIC the line you are entering is part of 
a program, you begin the line with a line number. A program line is 
stored in memory when you press CR, but it is not executed. The lines 
are stored in memory in line number sequence to form a GW-BASIC 
program. To execute the program press RUN CR. 

prompt: Message displayed on the screen to remind the user to do 
a specific action. 

reboot: To reload an operating system from disk into memory. 

record: A group of one or more consecutive fields on a related sub¬ 
ject. For example, an employee’s payroll record. A file is a collection 
of records. 
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redirecting standard I/O: You can redirect your GW-BASIC input and 
output by the GWBASIC command. Standard input can be redirected 
to any file, standard output to any file or device. 

relative coordinates: In graphics the x and y coordinates of a point 
on the screen specified as displacements from another point. 

reserved word: Synonymous with keyword. 

RS-232-C port: Synonymous with communications channel, used to 
transfer data to or from another computer or peripheral. 

scale factor: In graphics, a real number that, when multiplied by the 
distances given in the U, D, R, L, E, F, G, H commands of the DRAW 
statement, provides the actual distance moved in pixels. 

scanline: A horizontal line of pixels on the screen. 

scan code: An integer code (in decimal or hexadecimal form) that iden¬ 
tifies the position of a key on the keyboard. 

screen coordinates: In graphics, the cartesian coordinates of a point 
on the screen, expressed in pixels. 

scroll: To move the text display vertically or horizontally so as to show 
characters that do not fit on the screen. 

segment: The main memory is divided into segments of 64k-bytes 
each. Within a segment, a memory address may be specified as an 
offset from the beginning of the segment. 

sequential access: An access method in which records are process¬ 
ed in consecutive order, either from the beginning (sequential input 
or output), or the end of the file (append). 

single precision: If a number is not an integer and contains 7 or fewer 
digits it is a single precision number. 

soft key: Synonymous with function key 

soft key display: The display of the soft key values on the 25th screen 
line. 




stack: An area of memory in which data items are temporarily stored 
in a LIFO (Last In First Out) queue. 

statement: An instruction to the computer to perform some sequence 
of operations. 

string delimiter: A character that limits a string of characters and 
therefore cannot be part of the string. 

string expression: An expression that returns a string value. 

string variable: A simple variable or array element whose value is a 
string. 

subroutine: Either a machine language routine (which may be called 
by a CALL statement, or an USR function), or a section of a GW-BASIC 
program (which may be called by a GOSUB or ON... GOSUB state¬ 
ment). At the end of the execution of a subroutine, control is usually 
returned to the first statement following the calling statement. 

subscript: A positive integer which specifies the position of an array 
element within the array. 

text window: A rectangular portion of the screen where text is out¬ 
put. It may be defined by a VIEW PRINT or a WIDTH statement. 

tiling: In graphics, a rectangular struncture of bits used repeatedly to 
paint an area with a given pattern of colors. 

trap: A special form of a conditional breakpoint that is activated by 
an event to be intercepted. It also refers to the action to be taken after 
the interception. 

type declaration character: A special character placed at the end of 
a variable - It may be : % (integer variable),! (single-precision variable), 
# (double-precision variable), or $ (string variable). 

type of a variable: Indicates whether the variable is a string or a 
numeric variable and (if numeric) if it is an integer, a single-precision, 
or a double-precision variable. The type of a variable may be set by 
a DEF (INT, SNG, DBL, or STR) statement, or by a character defini¬ 
tion tag at the end of the variable name. 
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type of an expression: The type of an expression is the data-type 
(string, integer, single-precision, or double-precision) of the resulting 
evaluation of the expression. It depends on the type of its operands. 

typewriter keyboard: The central section of the keyboard that is us¬ 
ed as a standard typewriter keyboard. 

underflow: In an arithmetic operation, the generation of a quantity less 
than the minimum value different from zero that can be represented 
in number format. If an underflow occurs GW-BASIC supplies zero, 
and execution continues. 

user function: A function that the user must define before it is called 
(see DEF FN statement). 

variable: A named data item whose values may change during pro¬ 
gram execution. A variable may be a simple variable or an array ele¬ 
ment. The name of the variable also specifies its type (numeric or 
string). 

variable-length record: A record whose length is independent of the 
length of other records in the file. 

vector: A collection of variables of the same type under one name 
that can be ordered in a list. Each element of a vector may be address¬ 
ed by specifying the value of its subscript. 

viewport: A rectangular portion of the screen onto which window con¬ 
tents are mapped. A viewport is defined by a VIEW statement to display 
both graphics and text. It is possible to have more than one viewport 
on the screen, but only one will be current. 

visual page: The section of the screen buffer which is currently 
displayed on the screen. It may be different from the active page in 
Text Mode (see ’’active page”). 

wild card character: A special symbol used to represent any single 
character (?) or any string of characters (*) in a filename. 

window: The world coordinate space which is mapped onto the cur¬ 
rent viewport by the WINDOW statement. 







world coordinates: In graphics, the cartesian coordinates of a point 
of a figure to be displayed, expressed using the user-defined coordinate 
system. 

zooming: The technique of increasing or decreasing the size of the 
image to be displayed by changing the logical dimensions of the cur¬ 
rent viewport by the WINDOW statement. 
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H. ERROR CODES AND ERROR MESSAGES 




ABOUT THIS APPENDIX 


This appendix describes all error codes and messages given by 
GW-BASIC. 




ERROR CODES AND ERROR MESSAGES 


NUMBER 

MESSAGE 

1 

NEXT without FOR 

A variable in a NEXT statement does not corres¬ 
pond to any previously executed, unmatched FOR 
statement variable. 

2 

Syntax error 

A line is encountered which includes an incorrect 
sequence of characters (misspelled keyword, un¬ 
matched parenthesis, incorrect punctuation, etc). 
GW-BASIC automatically enters edit mode at the 
line that caused the error. 

3 

RETURN without GOSUB 

A RETURN statement is encountered for which 
there is no previous, unmatched GOSUB 
statement. 

4 

Out of DATA 

A READ statement is executed when there are no 
DATA statements with unread data remaining in the 
program. 

5 

Illegal function call 

A parameter that is out of range is passed to a 
numeric or string function. This FC error may also 
occur as the result of: 















NUMBER 

MESSAGE 



• a negative or unreasonably large subscript 

• a negative or zero argument with LOG 

• a negative argument to SQR 

• a negative mantissa with a noninteger exponent 

• a call to a USR function for which the starting ad¬ 
dress has not yet been given 

• an improper argument to MID$, LEFTS, RIGHTS, 

INP, OUT, WAIT, PEEK, POKE, TAB, SPC, 
STRINGS, SPACES, INSTR, or ON...GOTO 

• a negative record number used with GET(Files) 
or PUT(Files) statements 

6 

Overflow 

The result of a calculation is too large to be 
represented in GW-BASIC number format. If 
underflow occurs, the result is zero and execution 
continues without an error. 

7 

Out of memory 

A program is too big, or has too many loops, 
subroutines, variables, or has expressions that are 
too complicated to evaluate. 

8 

Undefined line number 

A nonexistent line is referenced in a GOTO, 
GOSUB, IF...THEN...ELSE, or DELETE statement. 

► 
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ERROR CODES AND ERROR MESSAGES 


NUMBER 

MESSAGE 

9 

Subscript out of range 

An array element is referenced either with a 
subscript that is outside the dimensions of the ar¬ 
ray or with the wrong number of subscripts. 

10 

Duplicate Definition 

Two DIM statements are given for the same array; 
or a DIM statement is given for an array after the 
default dimension of 10 has been established for 
that array; or an OPTION BASE is given after an 


array has been dimensioned. 

11 

Division by zero 


A division by zero is encountered in an expression; 
or, the value zero has been raised to a negative 
power. In the former case, the result is machine 
infinity (with the appropriate sign); in the latter case, 
the result is positive machine infinity. In both cases 
execution continues. 

12 

Illegal direct 

A statement that is illegal in direct mode is entered 
as a direct mode command. 

13 

Type mismatch 

A string variable name is assigned a numeric value 
or vice versa; a function that expects a numeric 
argument is given a string argument or vice versa. 
















NUMBER 

MESSAGE 

14 

Out of string space 

String variables have caused GW-BASIC to exceed 
the amount of free memory remaining. GW-BASIC 
will allocate string space dynamically, until it runs 
out of memory. 

15 

String too long 

An attempt is made to create a string more than 
255 characters long. 

16 

String formula too complex 

A string expression is too long or too complex to 
be processed. It should be broken into smaller 
expressions. 

17 

Can’t continue 

An attempt is made to continue a program that: 

• has halted due to an error 

• has been modified during a break in execution 

• does not exist 

18 

Undefined user function 

A USR function is called before the function defini¬ 
tion (DEF statement) is given. 
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NUMBER 

MESSAGE 

19 

No RESUME 

An error handling routine is entered but contains 
no RESUME statement. 

20 

RESUME without error 

A RESUME statement is encountered before an er¬ 
ror handling routine is entered. 

22 

Missing operand 

An expression contains an operator with no 
operand following it. 

23 

Line buffer overflow 

An attempt has been made to input a line that has 
too many characters. 

24 

Device Timeout 

GW-BASIC did not receive information from an I/O 
device within a predetermined amount of time. 

25 

Device fault 

An incorrect device designation has been entered. 

26 

FOR without NEXT 

A FOR statement was encountered without a mat¬ 
ching NEXT statement. 



















NUMBER 

MESSAGE 

27 

Out of Paper 

The printer is out of paper or is not switched on. 
Insert paper, ensure power is switched on and 
continue. 

29 

WHILE without WEND 

A WHILE statement does not have a matching 
WEND statement. 

30 

WEND without WHILE 

A WEND statement was encountered without a 
matching WHILE statement. 

50 

FIELD overflow 


A FIELD statement is attempting to allocate more 
bytes than were specified for the record length of 
a random file. 

51 

Internal error 

An internal malfunction has occurred in GW-BASIC. 

52 

Bad File number 

A statement or command references a file with a 
file number that is not OPEN or is out of the range 
of file numbers specified at initialization. This er¬ 
ror message is also given when the filename or 
pathname is specified incorrectly in an I/O state¬ 
ment or command. 
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ERROR CODES AND ERROR MESSAGES 


NUMBER 

MESSAGE 

53 

File not found 

An I/O statement or command references a file that 
does not exist, or specifies a path to a file 
incorrectly. 

54 

Bad file mode 

An attempt is made to use PUT(Files), GET(Files), 
to LOAD a random file, or to execute an OPEN 
statement with a file mode other than 1, 0, or R. 

55 

File already open 

A sequential output mode OPEN statement is 
issued for a file that is already open; or a KILL com¬ 
mand is given for a file that is open. 

57 

Device I/O Error 

An I/O error occurred on a disk I/O operation. It is 
a fatal error; i.e., the operating system cannot 
recover from the error. 

58 

File already exists 

The filename specified in a NAME command is 
identical to a filename already in use on the disk. 

61 

Disk full 

All disk storage space is in use. 

















NUMBER 

MESSAGE 


62 

Input past end 

An INPUT statement is executed after all the data 
in the file has been INPUT, or for a null (empty) file. 
To avoid this error, use the EOF function to detect 
the end-of-file. 

63 

Bad record number 

In a PUT(Files) or GET(Files) statement, the record 
number is either greater than the maximum allow¬ 
ed (16,777,215) or equal to zero. 

64 

Bad file name 

A pathname or filename is specified incorrectly with 
an I/O statement or command. 

66 

Direct statement in file 

A direct statement is encountered while LOADing 
an ASCII-format file. The LOAD is terminated. 

67 

Too many files 

An attempt is made to create a new file (using 
SAVE or OPEN) when all 255 directory entries are 
full. 

68 

Device Unavailable 

An attempt was made to open a file to a non¬ 
existent device. It may be that hardware did not ex¬ 
ist to support the device, such as LPT2: or LPT3:, 
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NUMBER 

MESSAGE 


or was disabled by the user. This occurs if an OPEN 
. ”COM1:... statement is executed after the user has 
disabled RS232 support via the /C:0 switch direc¬ 
tive in the GWBASIC command. 

69 

Communication buffer overflow 

Occurs when a communication input statement is 
executed but the input queue was already full. Use 
an ON ERROR GOTO statement to retry the input 
when this condition occurs. Subsequent inputs will 
attempt to clear this fault, unless characters con¬ 
tinue to be received faster than the program can 
process them. In this case several options are 
available: 

• increase the size of the COM receive buffer via 
the /C: switch 

• implement a ’’hand-shaking” protocol with the 
host/satellite such as XON/XOFF to turn transmit 
off long enough to catch up 

• use a lower baud rate for transmit and receive 

70 

Permission Denied 

This occurs when an attempt is made to write to 
a diskette that is write protected. Use an ON ER¬ 
ROR GOTO statement to detect this situation and 
request user action. 

Errors 71,72, and 74 are other possible ’’hard” disk 
errors. 

The error also occurs during LOCK, UNLOCK and 
OPEN statements, if access to a specified file is 
restricted or if MS-NET is not installed. 











NUMBER 

MESSAGE 

71 

Disk not ready 

Occurs when the diskette drive door is open, or a 
diskette is not in the drive. Again use an ON ER¬ 
ROR GOTO statement to recover. 

72 

Disk media error 

Occurs when a hardware or media fault is detected. 
This usually indicates damaged media. Copy any 
existing files to a new diskette and reformat the 
damaged diskette. FORMAT will flag the bad tracks 
and place them in a file ’’badtrack”. The remainder 
of the diskette is now usable. 

74 

Rename across disks 

An attempt was made to rename a file with a new 
drive designation. 

75 

Path/File Access Error 


During an OPEN, MKDIR, CHDIR, or RMDIR 
operation, MS-DOS was unable to make a correct 
Path to Filename connection. The operation is not 
completed. 

76 

Path not found 

An illegal form of pathname is used with an I/O 
statement or command. 
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NUMBER 

MESSAGE 

* * 

Can’t continue after SHELL 

No error number. Upon returning from a Child pro¬ 
cess, the SHELL statement discovers that there is 
not enough memory for GW-BASIC to continue. 
GW-BASIC closes any open files and exits to 
MS-DOS. 
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SPECIAL CHARACTERS 

! 3-4 
# 3-4 
$ 3-4 
% 3-4 
: 1-5 
? 8-260 

A 

ABS Function 8-26 
absolute coordinates 5-10 
absolute value 8-26 
access modes (files) 4-9 
access rights 8-189,8-224, 

8-329 

acknowledgement from 
device 8-161 
action verb 8-276 
addition 3-8 

address of variable 8-333,8-335 
ALT key 2-5 
AND 3-13 

animation 5-10, 8-279 
append mode 4-13,8-226 
arctangent of a number 8-28 
arithmetic operators 3-8 
array base 8-246 
array dimensioning 8-90 
arrays 3-5 
ASC Function 8-27 
ASCII character codes C-1 
ASCII code of character 8-27 
ASCII format 8-297 
aspect ratio 8-49 
assembly language 6-1 
assignment from DATA 8-281 
assignment 8-174 
asynchronous 
communications 7-1 
ATN Function 8-28 
AUTO Command 8-29 
automatic line 


numbering 2-21,8-29 

B 

background 5-3,5-5 
background colors 8-59... 
backslash 4-4 
backspace 2-5 
BEEP Statement 8-30 
bell 8-30 

bell character 8-30 
BLOAD Command 8-31 
BLOADing machine language 
subroutines 6-3 
branch to line 8-134 
BSAVE Command 8-33 
buffer allocation 8-116 
buffers I/O 7-1 
built-in functions 8-1 

C 

calculator mode 2-19 
CALL Statement 8-35 
calling machine language 
subroutines 6-1 
CALLS Statement 8-36 
caps lock 2-4 
carriage return key 2-4 
CDBL Function 8-37 
CHAIN Statement 8-38 
change current directory 8-43 
change line 8-101 
change line numbers 8-286 
channel for comms 8-232 
channel to file 8-224 
character at point 8-299 
character device driver 8-158 
character of ASCII code 8-45 
CHDIR Command 8-43 
check for end of file 8-107 
check for keystroke 8-146 
child processes 6-15 
CHR$ Function 8-45 
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CINT Function 8-46 
CIRCLE Command 8-47 
circle or elipse 8-49 
clear screen 8-57 
CLEAR Statement 8-53 
close data files 8-287 
close file or device 8-56 
CLOSE Statement 8-56 
CLS Statement 8-57,A-1 
COLOR Statement (SCREEN 0) 
8-59 

COLOR Statement (SCREEN 1) 
8-62,A-1 

COLOR Statement (SCREEN 2 
and 3) 8-65,A-1 
color an area 8-238 
color at point 8-299 
colors available 5-3 
COM(n) Statement 8-67 
commands 8-1 
comments 8-284 
COMMON Statement 8-69 
communications 7-1,2 
compatibility between versions 
of GW-BASIC A-1 
conditional branches 
8-143,8-214 
constants 3-1 
CONT Command 8-73 
continue after error trap 8-289 
control characters 2-4,5 
control data 8-158 
conversion of programs to 
GW-BASIC E-1 
conversion tables HEX-DEC 
D-1 

convert numeric to string 8-203 
convert string to 
numeric 8-76,8-332 
convert to double precision 
8-37 

convert to integer 8-46,8-158 
convert to single precision 8-75 
coordinates 5-9,8-250 


COS Function 8-74 
cosine of number 8-74 
CSNG Function 8-75 
CSRLIN Function 8-76 
current directory 4-4 
cursor 8-187 

cursor position (column) 8-257 
cursor position (line, row) 8-76 
CVD CVI CVS Functions 8-76 

D 

data segment 6-1 
DATA Statement 8-78 
date 8-80 

DATES Function and 
Statement 8-80 
debugging 8-327 
declaration tags 3-4 
DEFDBL Statement 8-88 
DEFFN Statement 8-82 
define common variables 8-69 
defining keys 8-166 
DEFINT Statement 8-88 
DEF SEG Statement 8-84 
DEFSNG Statement 8-88 
DEFSTR Statement 8-88 
DEF USR Statement 8-86 
delete characters 2-16 
DELETE Command 8-91 
delete file 8-170 
delete program 8-207 
derived mathematical 
functions B-1 
device controllers 6-16 
device errors 8-109 
devices 4-3 
DIM Statement 8-90 
dimension arrays 8-90 
dimensions of window 
(graphics) 8-346 
direct entry of keywords 2-7 
directories 4-4 
directory creation 8-201 
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directory removal 8-292 

disk drives 4-3 

disk files 4-1 

disk input/output 4-1 

display graphics image 8-276 

display pages 5-2 

division 3-8 

double precision 3-2 

draw circle, elipse or ray 8-47 

draw line or rectangle 8-174 

DRAW Statement 8-95 

drawing pictures 5-4 

drive letters 4-3 

duplex communication 7-3 

duration 8-309 

E 

e to a power 8-115 
EDIT Command 8-101 
editing a line 2-13 
elipse or circle 8-47 
ELSE 8-143 
end of program 8-102 
END Statement 8-102 
entering a program 2-20 
ENVIRON Statement 8-103 
ENVIRONS Function 8-105 
environment parameters 8-103 
EOF Function 8-107 
erase screen or window 8-57 
ERASE Statement 8-108 
ERDEV Statement 8-109 
ERDEV$ Function 8-109 
ERL Function 8-111 
ERR Function 8-111 
error codes 8-111 ,H-1 
ERROR Statement 8-113 
event trapping 6-12 
exchange variables 8-319 
execute MS-DOS program 
8-306 

execute program 2-24,8-295 
exit from GW-BASIC 2-2 


EXP Function 8-115 
exponential representation 3-2 
expressions 3-8 
extensions to file names 4-1 

F 

FIELD Statement 8-116 . 

file control blocks A-3,F-4 

file input 8-152 

file length 8-191 

file locking 8-189,8-329 

file names 4-2,8-119 

file numbers 4-2 

FILES Command 8-119 

FIX Function 8-121 

fixed point 3-1 

floating point 3-1 

FOR Statement 8-122 

foreground colors 8-59.. 

formatted output 8-194,8-262 

FRE Function 8-126 

frequency 8-309 

function keys 2-3,8-162,A-3 

functional operators 3-8 

functions 8-1 

G 

garbage collection 8-126 
generate error 8-113 
GET (COM Files) 

Statement 8-127 
GET (Files) Statement 8-128 
GET (Graphics) Statement 
8-129 

GOSUB Statement 8-132 
GOTO Statement 8-134 
graphics environment 5-1,8-300 
graphics macro language 8-96 
graphics modes 5-1 
GWBASIC Command 8-135 
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H 

halt program 8-315 
hardcopy 8-171 
hardware 6-16 
HE)<$ Function 8-142 
hexadecimal 3-2, 8-142 
high resolution 5-6,8-65,8-300 

I 

IF Statement 8-143 
initialization procedure 2-1 
INKEY$ Function 8-146 
INP Function 8-148 
input buffers 7-1 
INPUT Statement 8-149.A-1 
INPUT # Statement 8-152,A-1 
INPUTS Function 8-153 
inserting characters 2-15 
INSTR Function 8-156 
INT Function 8-158 
integer division 3-8,10 
integers 3-1 
internal data file 8-78 
internal representations F-3 
interrupt vectors 6-16 
interrupts 2-27 
IOCTL Statement 8-158 
IOCTL$ Function 8-161 

J 

justify 8-195 

K 

KEY Statement 8-162 
KEY (n) Statement 8-167 
keyboard 2-3 
keyboard buffer 8-146 
keyboard input 8-149 
keywords direct entry 2-7 
KILL Command 8-170 


L 

LCOPY Command 8-171 
left substring 8-172 
LEFTS Function 8-172 
LEN Function 8-173 
LET Statement 8-174 
line editing 2-8 
line format 1-5 
LINE INPUT # 

Statement 8-180 
LINE INPUT Statement 8-178 
line numbers 1-6, 8-286 
LINE Statement 8-175 
line width 8-342 
LIST Command 8-181 
list files in directory 8-119 
listing a program 2-22 
LLIST Command 8-183 
LOAD Command 8-184 
LOC Function 8-186 
LOCATE Statement 8-187,A-2 
LOCK Statement 8-189 
LOF Function 8-191 
LOG Function 8-192 
logical operators 3-8 
loop statements (FOR) 8-122 
loop while true (WHILE) 8-340 
lower bound 8-236 
LPOS Function 8-193 
LPRINT Statement 8-194 
LPRINT USING Statement 
8-194 

LSET and RSET 
Statements 8-195 

M 

machine language 
subroutines 6-1,8-96,8-331 
medium resolution 5-5,8-62, 
8-300 

memory image file load 8-31 
memory image file save 8-33 
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memory location 8-243,8-256 
memory management 6-17.F-1 
memory map F-8 
memory size of variables 3-5 
memory space available 8-126 
MERGE Command 8-197 
MID$ Function and 
Statement 8-198 
middle substring 8-198 
MKD$ Function 8-203 
MKDIR Command 8-201 
MKI$ Function 8-203 
MKS$ Function 8-203 
MOD modulus arithmetic 3-10 
mode change 
(Graphics/text) 8-300 
modes of operation 2-2 
modify a line or 
character 2-14,8-101 
monitor port 8-339 
monochrome 8-60 
MS-DOS 8-135,8-306,8-320 
multiplication 3-8 
music 8-244 
music buffer 8-248 
music control 8-249 

N 

NAME Command 8-205 

natural logarithm 8-115,8-192 

NEW Command 8-207 

NEXT 8-122 

NOT 3-13 

notes 8-310 

numeric keypad 2-7 

O 

OCT$ Function 8-207 
octal 3-2,8-207 
ON ... GOSUB / GOTO 
Statements 8-214 
ON COM (n) GOSUB 


Statements 8-208 
ON ERROR GOTO 
Statements 8-211 
ON KEY (n) GOSUB 
Statements 8-215 
ON PLAY (n) GOSUB 
Statements 8-219 
ON TIMER (n) GOSUB 
Statements 8-222 
OPEN COM Statement 8-232 
OPEN Statement 8-224 
operating modes 2-2 
operators 3-8 
OPTION BASE Statement 
8-236 

OUT Statement 8-237 
output buffers 7-1 
output data 8-259,8-356 
output to comms channel 8-273 
output to file 8-269,8-274 
overflow 3-10 

P 

PAINT Statement 8-238 
painting figures 5-5 
palette colors 8-59... 
passing arguments to machine 
language subroutines 6-1 
path names 4-4 
PEEK Function 8-243 
pixel color 8-253 
pixel setting 8-258,8-271 
PLAY Statement 8-244 
PLAY [ ON | OFF | STOP ] 
Statement 8-249 
PLAY (n) Function 8-248 
PMAP Function 8-250 
POINT Function 8-253 
POKE Statement 8-256 
POKEing machine language 
subroutines into memory 6-2 
ports 8-148,8-237,8-339 
POS Function 8-257 
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position in file 8-186 
precision of variables 8-88 
PRESET Statement 8-258 
PRINT # Statement 8-269 
PRINT # USING 
Statement 8-269 
print head position 8-193 
PRINT Statement 8-259 
PRINT USING Statement 8-262 
printed list 8-183 
printer output 8-184 
program end 8-102 
program list 8-181 
program load 8-184 
program trace 8-327 
prompt 8-149 
protecting files 4-9 
PSET Statement 8-271 
PUT (COM Files) Statement 
8-273 

PUT (Files) Statement 8-274 
PUT (Graphics) Statement 
8-276 

R 

random access files 4-13 
random numbers 8-280,8-294 
RANDOMIZE Statement 8-280 
ray, elipse or circles 8-47 
read byte from port 8-148 
read bytes from 
communications buffers 
8-127 

read graphics image 
to array 8-129 
read record from file 8-128 
READ Statement 8-281 
real time 8-326 
relational operators 3-8,3-11 
relative coordinates 5-9 
REM Statement 8-284 
remove arrays 8-108 
remove program lines 8-89 


rename file 8-205 
RENUM Command 8-286 
reseed 8-280 
reserved words 1-8 
RESET Command 8-287 
resident subroutines 6-17 
RESTORE Statement 8-288 
resume program execution 8-73 
RESUME Statement 8-289 
return a value 8-1 
RETURN Statement 8-132 
return to MS-DOS 8-320 
right substring 8-290 
RIGHTS Function 8-290 
RMDIR Command 8-292 
RND Function 8-294 
RSET and LSET 
Statement 8-195 
RUN Command 8-295 
running a program 2-25 

S 

SAVE Command 8-297 
saving a program 2-22 
screen coordinates 5-9 
screen device 6-16 
screen editor 2-8 
SCREEN Function 8-299,A-2 
SCREEN Scrolling A-3 
SCREEN Statement 8-300 
segments (data) 6-1 
segments 6-17,8-35 
sequential access files 4-10 
SGN Function 8-305 
SHELL Command 8-306,A-2 
shift keys 2-4 
sign 8-305 
simulate error 8-113 
SIN Function 8-308 
sine of number 8-308 
single precision 3-2 
skip spaces 8-313 
SOUND Statement 8-309 
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SPACE$ Function 8-312 
spaces 8-312,8-313 
SPC Function 8-313 
special characters 1-7 
SQR Function 8-314 
square root 8-314 
stack memory 6-1 
start address of segment 8-84 
statements 8-1 
STOP Statement 8-315 
store program on disk 8-297 
STR$ Function 8-316 
string input 8-153 
string length 8-173 
string of ASCII code 8-316 
string of characters 8-317 
string of spaces 8-312 
STRINGS Function 8-317 
style 8-176 
subroutine 8-132 
substring 8-156,8-172,8-198, 
8-290 

subtraction 3-8 

super resolution 5-7,8-65,8-300 
suspend execution 8-339 
SWAP Statement 8-319 
syntax conventions 1-2 
SYSTEM Command 8-320 
system date 8-80 
system time 8-322 

T 

TAB Function 8-321 
tabulate cursor 8-321 
tags variable declaration 3-4 
TAN Function 8-332 
tangent of number 8-322 
tempos (music) 8-311 
text mode 5-2,8-59,8-300 
THEN Statement 8-143 
TIMES Statement and 
Function 8-323 
TIMER Function 8-326 


TO 8-122 

trace program flow 8-327 
transfer control to another 
program 8-38 

transfer control to line 8-134 
transfer control to machine 
language subroutine 6-5,8-35 
transfer control to 
subroutine 8-132 
transformations 5-8 
trapping comms 8-67,8-208 
trapping errors 8-211 
trapping keys 8-215 
trapping music 8-219 
trapping real time 8-222 
TROFF Command 8-327 
TRON Command 8-327 
truncated integer 8-121 
tty program 7-3 
type conversions 3-6 
type of variables 8-88 

U 

unconditional branch 8-134 
underlined characters 8-59 
UNLOCK Statement 8-329 
USING 8-262 
user functions 6-10,8-82 
USR Function 8-331 

V 

VAL Function 8-332 
variable address 8-333,8-335 
variable types 3-3 
VARPTR Function 8-333 
VARPTRS Function 8-335 
Version A-1 

VIEW PRINT Statement A-2 
VIEW Statement 8-336 
viewport graphics 8-336 
viewports and windows 5-8 
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w 


WAIT Statement 8-339 
WHILE ... WEND 
Statements 8-340 
WIDTH # Statement 8-342 
WIDTH Statement 8-342,A-3 
wild card characters 4-7 
window and viewports 5-8 
WINDOW Statement 8-346 
world coordinates 5-9,8-346 
write byte to port 8-237 
WRITE Statement 8-356 
WRITE $ Statement 8-357 

X,z 

XOR 3-13,A-1 
zero all variables 8-53 
zooming 5-8,8-353 
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NOTICE 


Ing. C. Olivetti & C., S.p.A. reserves the right to make any changes 
in the product described in this manual at any time and without notice. 

This manual is licensed to the Customer under the conditions contained 
in the User License enclosed with the Program to which the manual 
refers. 
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